User:Monster Iestyn/Source Code Documentation/m_fixed.h

From SRB2 Wiki
Jump to navigation Jump to search


Online link GitHub entry
File type C header file
#include guard __M_FIXED__

This header file contains the math functions for (16.16) fixed point numbers, and the definition of the fixed_t type.

Includes

The fixed_t type

Typedefs

Name Type Description
fixed_t INT32 The fixed point number data type

Macros

Macro Defined as Description
FRACBITS 16 The number of bits reserved for the fraction in the fixed point number implementation.
FRACUNIT (1<<FRACBITS) (65536) The size of a single unit in the fixed point number implementation. In many places in SRB2's source code this is commonly considered the basic unit of measurement for distances, speeds, and sometimes angles.
FRACMASK (FRACUNIT -1) (65535)
FIXED_TO_FLOAT(x) 
(((float)(x)) / ((float)FRACUNIT))
Converts a fixed_t integer to a floating point number.

e.g. FIXED_TO_FLOAT(FRACUNIT) → 1.0f

FLOAT_TO_FIXED(f) 
(fixed_t)((f) * ((float)FRACUNIT))
Converts floating point number to a fixed_t integer.

e.g. FLOAT_TO_FIXED(1.0f) → FRACUNIT

Fixed-point math functions

Function prototypes

Function name Return type Params Defined in Attributes Description/Other notes
Visual C++
FixedMul fixed_t fixed_t a,
fixed_t b 		tmap_vc.nas __cdecl Returns the result of multiplying a by b in the fixed-point scale.

(see FixedMul/FixedDiv2 section below).

FixedDiv2 fixed_t fixed_t a,
fixed_t b 		tmap_vc.nas __cdecl Returns the result of dividing a by b in the fixed-point scale. This function is called as part of the FixedDiv function.

(see FixedMul/FixedDiv2 section below).

Other (FixedMul/FixedDiv2)
FixedMul fixed_t fixed_t a,
fixed_t b 		m_fixed.c FUNCMATH Returns the result of multiplying a by b in the fixed-point scale.

Note: This prototype is used only if the macro __USE_C_FIXEDMUL__ is defined (see FixedMul/FixedDiv2 section below).

FixedDiv2 fixed_t fixed_t a,
fixed_t b 		m_fixed.c FUNCMATH Returns the result of dividing a by b in the fixed-point scale. This function is called as part of the FixedDiv function.

Note: This prototype is used only if the macro __USE_C_FIXEDDIV__ is defined (see FixedMul/FixedDiv2 section below).

Common
FixedSqrt fixed_t fixed_t x m_fixed.c FUNCMATH Returns the square root of x in the fixed-point scale.
FixedHypot fixed_t fixed_t x,
fixed_t y 		m_fixed.c FUNCMATH Returns the hypotenuse of x and y in the fixed-point scale (i.e. the length of the longest side of a right-angled triangle with sides x and y also present).

Inline functions

These functions have their function bodies actually defined within m_fixed.h itself rather than in m_fixed.c, unlike the functions that use prototypes.

Function name Return type Params Attributes Description/Other notes
FixedMul fixed_t fixed_t a,
fixed_t b 		FUNCMATH Returns the result of multiplying a by b in the fixed-point scale. See FixedMul/FixedDiv2 for more details.
FixedDiv2 fixed_t fixed_t a,
fixed_t b 		FUNCMATH Returns the result of dividing a by b in the fixed-point scale. This function is called as part of the FixedDiv function. See FixedMul/FixedDiv2 for more details.
FixedInt fixed_t fixed_t a FUNCMATH,
FUNCINLINE,
static,
ATTRINLINE 		Returns the integer component of a.
FixedDiv fixed_t fixed_t a,
fixed_t b 		FUNCMATH,
FUNCINLINE,
static,
ATTRINLINE 		Returns the result of dividing a by b in the fixed-point scale. Unlike FixedDiv2, which is called by this function, this also accounts for instances where a is a much larger value than b, returning INT32_MAX or INT32_MIN based on the signs of the two values.
FixedRem fixed_t fixed_t x,
fixed_t y 		FUNCMATH,
FUNCINLINE,
static,
ATTRINLINE 		Returns the remainder of dividing x by y in the fixed-point scale.
FixedFloor fixed_t fixed_t x FUNCMATH,
FUNCINLINE,
static,
ATTRINLINE 		Returns the floor of x (the largest integer that is not larger than x) in the fixed-point scale.
FixedTrunc fixed_t fixed_t x FUNCMATH,
FUNCINLINE,
static,
ATTRINLINE 		Returns the value of x rounded to the nearest whole number towards 0 (or x truncated to zero decimal digits) in the fixed-point scale.
FixedCeil fixed_t fixed_t x FUNCMATH,
FUNCINLINE,
static,
ATTRINLINE 		Returns the ceiling of x (the smallest integer that is not smaller than x) in the fixed-point scale.
FixedRound fixed_t fixed_t x FUNCMATH,
FUNCINLINE,
static,
ATTRINLINE 		Returns the value of x rounded to the nearest whole number away from 0 in the fixed-point scale.

FixedMul/FixedDiv2

Unlike the other functions, FixedMul and FixedDiv2 (not to be confused with FixedDiv) may be optimised using assembly code depending on the system. If this cannot be done, the macros __USE_C_FIXEDMUL__ and/or __USE_C_FIXEDDIV__ will be defined to tell the compiler to use the C definitions of FixedMul and FixedDiv2 instead, respectively.

Compiler/System Other requirements FixedMul FixedDiv2
Watcom C/C++ FRACBITS == 16 
#pragma aux FixedMul =  \
	"imul ebx",         \
	"shrd eax,edx,16"   \
	parm    [eax] [ebx] \
	value   [eax]       \
	modify exact [eax edx]

#pragma aux FixedDiv2 = \
	"cdq",              \
	"shld edx,eax,16",  \
	"sal eax,16",       \
	"idiv ebx"          \
	parm    [eax] [ebx] \
	value   [eax]       \
	modify exact [eax edx]
GCC, i386 NOASM not defined ASM code (ret = return value): 
 "imull %2;"
 "shrdl %3,%%edx,%0;"
:"=a" (ret)
:"0" (a), "r" (b)
, "I" (FRACBITS)
:"cc", "%edx"
ASM code (ret = return value): 
  "movl  %1,%%edx;"
  "sarl  $31,%%edx;"
  "shldl %3,%1,%%edx;"
  "sall  %3,%0;"
  "idivl %2;"
: "=a" (ret)
: "0" (a), "r" (b)
, "I" (FRACBITS)
: "%edx"
GCC, ARM (not Thumb) NOASM not defined ASM code (ret = return value): 
  "smull %[lo], r1, %[a], %[b];"
  "mov %[lo], %[lo], lsr %3;"
  "orr %[lo], %[lo], r1, lsl %3;"
: [lo] "=&r" (ret)
: [a] "r" (a), [b] "r" (b)
, "i" (FRACBITS)
: "r1"
__USE_C_FIXEDDIV__ defined
Visual C++ USEASM defined,
FRACBITS == 16 		ASM code defined in tmap_vc.nas ASM code defined in tmap_vc.nas
Other __USE_C_FIXEDMUL__ defined __USE_C_FIXEDDIV__ defined

Fixed-point vector math

Typedefs

Name Type Unpadded size (bytes) Description
vector2_t struct 8 The data structure of a fixed_t 2D vector.
vector3_t struct 12 The data structure of a fixed_t 3D vector.
matrix_t struct 64 The data structure of a fixed_t 4×4 matrix.

Structs

vector2_t

Data name Data type Description
x fixed_t The vector's X component
y fixed_t The vector's Y component

vector3_t

Data name Data type Description
x
y
z 		fixed_t The vector's X, Y and Z components

matrix_t

Data name Data type Description
m[16] fixed_t The matrix's elements array. Individual elements in the matrix are accessed using matrix->m[col*4 + row], where col and row are integers between 0 and 4.

Function prototypes

2D vector functions

Function name Return type Params Defined in Description
FV2_Load vector2_t * vector2_t *vec,
fixed_t x,
fixed_t y 		m_fixed.c Loads the given X and Y values into vec. Returns the modified vec.
FV2_UnLoad vector2_t * vector2_t *vec,
fixed_t *x,
fixed_t *y 		m_fixed.c Unloads the given X and Y values from vec into the x and y pointers given. Returns vec.
FV2_Copy vector2_t * vector2_t *a_o,
const vector2_t *a_i 		m_fixed.c Copies the vector a_i to the vector a_o. Returns the modified a_o.
FV2_AddEx vector2_t * const vector2_t *a_i,
const vector2_t *a_c,
vector2_t *a_o 		m_fixed.c Adds the components of a_c to a_i and stores the result in a_o. Returns the modified a_o.
FV2_Add vector2_t * vector2_t *a_i,
const vector2_t *a_c 		m_fixed.c Adds the components of a_c to a_i. Returns the modified a_i.
FV2_SubEx vector2_t * const vector2_t *a_i,
const vector2_t *a_c,
vector2_t *a_o 		m_fixed.c Subtracts the components of a_c from a_i and stores the result to a_o. Returns the modified a_o.
FV2_Sub vector2_t * vector2_t *a_i,
const vector2_t *a_c 		m_fixed.c Subtracts the components of a_c from a_i. Returns the modified a_i.
FV2_MulEx vector2_t * const vector2_t *a_i,
vector2_t a_c,
vector2_t *a_o 		m_fixed.c Multiplies the components of a_i by a_c and stores the result in a_o. Returns the modified a_o.
FV2_Mul vector2_t * vector2_t *a_i,
vector2_t a_c 		m_fixed.c Multiplies the components of a_i by a_c. Returns the modified a_i.
FV2_DivideEx vector2_t * const vector2_t *a_i,
vector2_t a_c,
vector2_t *a_o 		m_fixed.c Divides the components of a_i by a_c and stores the result in a_o. Returns the modified a_o.
FV2_Divide vector2_t * vector2_t *a_i,
vector2_t a_c 		m_fixed.c Divides the components of a_i by a_c. Returns the modified a_i.
FV2_Midpoint vector2_t * const vector2_t *a_1,
const vector2_t *a_2,
vector2_t *a_o 		m_fixed.c Calculates the midpoint between a_1 and a_2 and stores the result in a_o. Returns the modified a_o.
FV2_Distance fixed_t const vector2_t *p1,
const vector2_t *p2 		m_fixed.c Calculates and returns the distance between p1 and p2.
FV2_Magnitude fixed_t const vector2_t *a_normal m_fixed.c Calculates and returns the magnitude of a_normal.
FV2_NormalizeEx fixed_t const vector2_t *a_normal,
vector2_t *a_o 		m_fixed.c Gets the normalised vector (a.k.a. the unit vector) of a_normal and stores the result in a_o. Returns the magnitude of a_normal.
FV2_Normalize fixed_t vector2_t *a_normal m_fixed.c Normalises the vector a_normal (i.e. turning it into its normalised/unit vector). Returns the magnitude of a_normal.
FV2_NegateEx vector2_t * const vector2_t *a_1,
vector2_t *a_o 		m_fixed.c Calculates the negatated components of a_1 and stores the results in a_o. Returns the modified a_o.
FV2_Negate vector2_t * vector2_t *a_1 m_fixed.c Negates the components of a_1. Returns the modified a_1.
FV2_Equal boolean const vector2_t *a_1,
const vector2_t *a_2 		m_fixed.c Returns true if either the X or Y components of the two vectors are equal, returns false if not or both vectors are 0 in all components.
FV2_Dot fixed_t const vector2_t *a_1,
const vector2_t *a_2 		m_fixed.c Calculates and returns the dot product of a_1 and a_2.
FV2_Point2Vec vector2_t * const vector2_t *point1,
const vector2_t *point2,
vector2_t *a_o 		m_fixed.c Given two point vectors point1 and point2, this creates a vector between them and stores the result in a_o. Returns the modified a_o.

3D vector functions

Function name Return type Params Defined in Description
FV3_Load vector3_t * vector3_t *vec,
fixed_t x,
fixed_t y,
fixed_t z 		m_fixed.c Loads the given X, Y and Z values into vec. Returns the modified vec.
FV3_UnLoad vector3_t * vector3_t *vec,
fixed_t *x,
fixed_t *y,
fixed_t *z 		m_fixed.c Unloads the given X, Y and Z values from vec into the x, y and z pointers given. Returns vec.
FV3_Copy vector3_t * vector3_t *a_o,
const vector3_t *a_i 		m_fixed.c Copies the vector a_i to the vector a_o. Returns the modified a_o.
FV3_AddEx vector3_t * const vector3_t *a_i,
const vector3_t *a_c,
vector3_t *a_o 		m_fixed.c Adds the components of a_c to a_i and stores the result in a_o. Returns the modified a_o.
FV3_Add vector3_t * vector3_t *a_i,
const vector3_t *a_c 		m_fixed.c Adds the components of a_c to a_i. Returns the modified a_i.
FV3_SubEx vector3_t * const vector3_t *a_i,
const vector3_t *a_c,
vector3_t *a_o 		m_fixed.c Subtracts the components of a_c from a_i and stores the result to a_o. Returns the modified a_o.
FV3_Sub vector3_t * vector3_t *a_i,
const vector3_t *a_c 		m_fixed.c Subtracts the components of a_c from a_i. Returns the modified a_i.
FV3_MulEx vector3_t * const vector3_t *a_i,
vector3_t a_c,
vector3_t *a_o 		m_fixed.c Multiplies the components of a_i by a_c and stores the result in a_o. Returns the modified a_o.
FV3_Mul vector3_t * vector3_t *a_i,
vector3_t a_c 		m_fixed.c Multiplies the components of a_i by a_c. Returns the modified a_i.
FV3_DivideEx vector3_t * const vector3_t *a_i,
vector3_t a_c,
vector3_t *a_o 		m_fixed.c Divides the components of a_i by a_c and stores the result in a_o. Returns the modified a_o.
FV3_Divide vector3_t * vector3_t *a_i,
vector3_t a_c 		m_fixed.c Divides the components of a_i by a_c. Returns the modified a_i.
FV3_Midpoint vector3_t * const vector3_t *a_1,
const vector3_t *a_2,
vector3_t *a_o 		m_fixed.c Calculates the midpoint between a_1 and a_2 and stores the result in a_o. Returns the modified a_o.
FV3_Distance fixed_t const vector3_t *p1,
const vector3_t *p2 		m_fixed.c Calculates and returns the distance between p1 and p2.
FV3_Magnitude fixed_t const vector3_t *a_normal m_fixed.c Calculates and returns the magnitude of a_normal.
FV3_NormalizeEx fixed_t const vector3_t *a_normal,
vector3_t *a_o 		m_fixed.c Gets the normalised vector (a.k.a. the unit vector) of a_normal and stores the result in a_o. Returns the magnitude of a_normal.
FV3_Normalize fixed_t vector3_t *a_normal m_fixed.c Normalises the vector a_normal (i.e. turning it into its normalised/unit vector). Returns the magnitude of a_normal.
FV3_NegateEx vector3_t * const vector3_t *a_1,
vector3_t *a_o 		m_fixed.c Calculates the negatated components of a_1 and stores the results in a_o. Returns the modified a_o.
FV3_Negate vector3_t * vector3_t *a_1 m_fixed.c Negates the components of a_1. Returns the modified a_1.
FV3_Equal boolean const vector3_t *a_1,
const vector3_t *a_2 		m_fixed.c Returns true if either the X, Y or Z components of the two vectors are equal, returns false if not or both vectors are 0 in all components.
FV3_Dot fixed_t const vector3_t *a_1,
const vector3_t *a_2 		m_fixed.c Calculates and returns the dot product of a_1 and a_2.
FV3_Cross vector3_t * const vector3_t *a_1,
const vector3_t *a_2,
vector3_t *a_o 		m_fixed.c Calculates the cross product of a_1 and a_2 and stores the result in a_o. Returns the modified a_o.
FV3_ClosestPointOnLine vector3_t * const vector3_t *Line,
const vector3_t *p,
vector3_t *out 		m_fixed.c Finds the point on a line closest to the specified point. Line is the line vector (should be an array of 2 point vectors), p is the point vector, and out is the vector to store the result in.
FV3_ClosestPointOnTriangle void const vector3_t *tri,
const vector3_t *point,
vector3_t *result 		m_fixed.c Given a triangle and a point, the closest point on the edge of the triangle is returned. tri is the triangle vector (should be an array of 3 point vectors), point is the point vector, and result is the vector to store the result in.
FV3_Point2Vec vector3_t * const vector3_t *point1,
const vector3_t *point2,
vector3_t *a_o 		m_fixed.c Given two point vectors point1 and point2, this creates a vector between them and stores the result in a_o. Returns the modified a_o.
FV3_Normal void const vector3_t *a_triangle,
vector3_t *a_normal 		m_fixed.c Calculates the normal of a polygon. a_triangle is the triangle vector (should be an array of 3 point vectors), and a_normal is the vector to store the result in.
FV3_PlaneDistance fixed_t const vector3_t *a_normal,
const vector3_t *a_point 		m_fixed.c Calculates and returns distance between a plane and the origin.
FV3_IntersectedPlane boolean const vector3_t *a_triangle,
const vector3_t *a_line,
vector3_t *a_normal,
fixed_t *originDistance 		m_fixed.c Returns true if the plane is intersected, returns false if not.
FV3_PlaneIntersection fixed_t const vector3_t *pOrigin,
const vector3_t *pNormal,
const vector3_t *rOrigin,
const vector3_t *rNormal 		m_fixed.c Returns the distance from rOrigin to where the ray intersects the plane. Assumes you already know it intersects the plane.
FV3_IntersectRaySphere fixed_t const vector3_t *rO,
const vector3_t *rV,
const vector3_t *sO,
fixed_t sR 		m_fixed.c This function calculates whether a ray with origin vector rO and direction vector rV intersects a sphere with origin vector sO and radius sR. If it does, it returns the distance from the ray's origin to the first intersection point with the sphere along the ray. If it does not, it returns -1*FRACUNIT.

Note that rV is expected to be a normalized vector.

FV3_IntersectionPoint vector3_t * const vector3_t *vNormal,
const vector3_t *vLine,
fixed_t distance,
vector3_t *ReturnVec 		m_fixed.c Returns the intersection point of the line that intersects the plane.
FV3_PointOnLineSide UINT8 const vector3_t *point,
const vector3_t *line 		m_fixed.c If on the front side of the line, returns 1. If on the back side of the line, returns 0. 2D only.
FV3_PointInsideBox boolean const vector3_t *point,
const vector3_t *box 		m_fixed.c Given four points of a box, determines if the supplied point is inside the box or not.

Matrix functions

Function name Return type Params Defined in Description
FM_LoadIdentity void matrix_t *matrix m_fixed.c Loads the identity matrix into a matrix.
FM_CreateObjectMatrix void matrix_t *matrix,
fixed_t x,
fixed_t y,
fixed_t z,
fixed_t anglex,
fixed_t angley,
fixed_t anglez,
fixed_t upx,
fixed_t upy,
fixed_t upz,
fixed_t radius 		m_fixed.c Creates a matrix that can be used for adjusting the position of an object.
FM_MultMatrixVec3 void const matrix_t *matrix,
const vector3_t *vec,
vector3_t *out 		m_fixed.c Multiplies a vector by the specified matrix.
FM_MultMatrix void matrix_t *dest,
const matrix_t *multme 		m_fixed.c Multiplies one matrix into another.
FM_Translate void matrix_t *dest,
fixed_t x,
fixed_t y,
fixed_t z 		m_fixed.c Translates a matrix.
FM_Scale void matrix_t *dest,
fixed_t x,
fixed_t y,
fixed_t z 		m_fixed.c Scales a matrix.
Retrieved from "https://wiki.srb2.org/w/index.php?title=User:Monster_Iestyn/Source_Code_Documentation/m_fixed.h&oldid=114529"