2.3 Function specifications

＜ Trigonometric function＞

one View table

Title function specification

Function sin function

Function name MTH_Sin

No 1

Format

Fixed32 val = MTH_Sin(Fixed32 degree)

input

degree: angle from −180.0 to 180.0

output

none

function value

val: sin value

function

Returns the sin value of the specified angle.

one View table	Title function specification	Function cos function	Function name MTH_Cos	No 2

Format

Fixed32 val = MTH_Cos(Fixed32 degree)

input

degree: angle from −180.0 to 180.0

output

none

function value

val: cos value

function

Returns the cos value of the specified angle.

one View table

Title function specification

Function atan function

Function name MTH_Atan

No 3

Format

Fixed32 degree = MTH_Atan(Fixed32 y, Fixed32 x)

input

y: height from −1.0 to 1.0

x: base from −1.0 to 1.0

output

none

function value

degree: angle from −180.0 to 180.0

function

Returns the atan value from the specified x, y values.

＜ 3D matrix calculation processing＞

one View table

Title function specification

Function Matrix table initialization

Function name MTH_InitialMatrix

No 4

Format

void MTH_InitialMatrix(MthMatrixTbl *matrixTbl, Uint16 stackSize,MthMatrix *matrix)

input

matrixTbl	: Matrix table
stackSize	: Maximum number of entries in matrix stack
matrix	: Matrix stack area

output

matrixTbl: matrix table

function value

none

function

Initialize the matrix table.

one View table

Title function specification

Function Clear current matrix

Function name MTH_ClearMatrix

No 5

Format

void MTH_ClearMatrix(MthMatrixTbl *matrixTbl)

input

matrixTbl: matrix table

output

none

function value

none

function

Clears the current matrix in the matrix stack to the identity matrix.

one View table

Title function specification

Function matrix push

Function name MTH_PushMatrix

No 6

Format

void MTH_PushMatrix(MthMatrixTbl *matrixTbl)

input

matrixTbl: matrix table

output

none

function value

none

function

Push the current matrix.

one View table

Title function specification

Function matrix pop

Function name MTH_PopMatrix

No 7

Format

void MTH_PopMatrix(MthMatrixTbl *matrixTbl)

input

matrixTbl: matrix table

output

none

function value

none

function

Pop the current matrix.

one View table

Title function specification

Function Matrix synthesis/parallel movement

Function name MTH_MoveMatrix

No 8

Format

void MTH_MoveMatrix(MthMatrixTbl *matrixTbl, Fixed32 x, Fixed32 y, Fixed32 z)

input

matrixTbl	: Matrix table
x	: Amount of movement in the X direction
y	: Amount of movement in the Y direction
z	: Movement amount in Z direction

output

none

function value

none

function

Performs matrix synthesis of XYZ translation on the current matrix.

one View table

Title function specification

Function Matrix synthesis/X-axis rotation

Function name MTH_RotateMatrixX

No 9

Format

void MTH_RotateMatrixX(MthMatrixTbl *matrixTbl, Fixed32 xDegree)

input

matrixTbl	: Matrix table
xDegree	: Rotation angle of X axis (range from -180 to 180)

output

none

function value

none

function

Performs matrix synthesis of X-axis rotation on the current matrix.

one View table

Title function specification

Function Matrix synthesis/Y-axis rotation

Function name MTH_RotateMatrixY

No 10

Format

void MTH_RotateMatrixY(MthMatrixTbl *matrixTbl, Fixed32 yDegree)

input

matrixTbl	: Matrix table
yDegree	: Y-axis rotation angle (range -180 to 180)

output

none

function value

none

function

Performs matrix synthesis of Y-axis rotation on the current matrix.

one View table

Title function specification

Function Matrix synthesis/Z-axis rotation

Function name MTH_RotateMatrixZ

No 11

Format

void MTH_RotateMatrixZ(MthMatrixTbl *matrixTbl, Fixed32 zDegree)

input

matrixTbl	: Matrix table
zDegree	: Rotation angle of Z axis (range from -180 to 180)

output

none

function value

none

function

Performs matrix synthesis of Z-axis rotation on the current matrix.

one View table

Title function specification

Function Matrix synthesis/Z-axis sign inversion

Function name MTH_ReverseZ

No 12

Format

void MTH_ReverseZ(MthMatrixTbl *matrixTbl)

input

matrixTbl: matrix table

output

none

function value

none

function

Performs matrix synthesis with Z-axis sign inversion for the current matrix.

one View table

Title function specification

Function Matrix operation/multiplication

Function name MTH_MulMatrix

No 13

Format

void MTH_MulMatrix(MthMatrix *a, MthMatrix *b, MthMatrix *c)

input

a	: Multiplicand matrix
b	: Multiplier matrix

output

c: Multiplication result matrix

function value

none

function

Multiply matrices a and b and output to c.

one View table

Title function specification

Function Matrix calculation/vertex coordinate transformation

Function name MTH_CordTrans

No 14

Format

void MTH_CoordTrans(MthMatrix *matrix, MthXyz *src, MthXyz *ans)

input

matrix	: conversion matrix
src	: Vertex coordinates before conversion

output

ans: Vertex coordinates after transformation

function value

none

function

Transforms the vertex coordinates using the transformation matrix.

one View table

Title function specification

Function Matrix calculation/normal vector Coordinate transformation

Function name MTH_NormalTrans

No 15

Format

void MTH_NormalTrans(MthMatrix *matrix, MthXyz *src, MthXyz *ans)

input

matrix	: Conversion matrix
src	: Normal vector before conversion

output

ans: Normal vector after conversion

function value

none

function

Transforms the coordinates of the normal vector using the transformation matrix.

＜ 3D polygon data coordinate conversion processing by DSP＞

one View table

Title function specification

Function Initialization of coordinate transformation processing

Function name MTH_PolyDataTransInit

No 16

Format

void MTH_PolyDataTransInit(void)

input

none

output

none

function value

none

function

Load the DSP initialization and coordinate conversion processing program.

one View table

Title function specification

Function Coordinate transformation of 3D polygon data

Function name MTH_PolyDataTransExec

No 17

Format

void MTH_PolyDataTransExec(MthPolyTransParm *polyTransParm)

input

polyTransParm: Coordinate transformation parameter table

output

polyTransParm: The following area of the coordinate transformation parameter table will be output.

surfBright	Brightness calculation result of polygon surface
transViewVertAns	Vertex data after viewpoint coordinate transformation
vertBright	Vertex brightness calculation result
transWorldVertAns	Vertex data after world coordinate transformation

function value

none

function

DSP performs the following series of processing on the polygon data string (3D object) used in the 3D sprite display library.

・Hidden surface detection and brightness calculation of polygon surfaces

-Related parameter items-
<input>  surfCount          Number of polygon surfaces
         surfPoint          Representative point table of polygon surface for calculating surface brightness
         surfNormal         Normal table of polygon surface
         matrix             Conversion matrix to viewpoint coordinate system
         lightVector        Light source vector in viewpoint coordinate system
<output> surfBright         Polygon surface brightness calculation result table

         bit31                                 bit0
           o... .... .... .... .... .... ...o oooo 
           |                                | ||||
           |                                +-++++----Brightness
           |                                          0x00：Darkest
           |                                          0x1f：Brightest
           +--------- 1:Hidden surface
                      0:Display surface

・Conversion processing of vertices to viewpoint coordinate system

-Related parameter items-
<input>  transViewVertCount       Number of vertex entries for viewpoint coordinate transformation
         transViewVertSrc         Vertex data table before viewpoint coordinate transformation
         viewMatrix               Transformation matrix to viewpoint coordinate system
<output> transViewVertAns         Vertex data table after viewpoint coordinate transformation

・Calculation of brightness of vertices for Gouraud display (optional)

-Related parameter items-
<input>  gourVertCount            Number of vertex entries for vertex brightness calculation
                                  If =0, vertex brightness calculation is not performed
         vertNormal               Vertex normal table for vertex brightness calculation
         matrix                   Conversion matrix to viewpoint coordinate system
         lightVector              Light source vector in viewpoint coordinate system
<output> vertBright               Vertex brightness calculation result table
                                  0x00 = darkest
                                  0x1f = brightest

・Conversion processing of vertices to world coordinate system

-Related parameter items-
<input>  transWorldVertCount      Number of vertex entries for world coordinate transformation
                                  If = 0, the world coordinate system of the vertex is not transformed
         transWorldVertSrc        Vertex data table before world coordinate transformation
         worldMatrix              Transformation matrix to world coordinate system
<output> transWorldVertAns        Vertex data table after world coordinate transformation

one View table

Title function specification

Function Checking the completion of coordinate transformation processing

Function name MTH_PolyDataTransCheck

No 18

Format

voidMTH_PolyDataTransCheck(void)

input

none

output

none

function value

none

function

Wait until the coordinate conversion process by DSP is completed.

＜ Perspective transformation processing＞

one View table

Title function specification

Function Perspective transformation of 3D points

Function name MTH_Pers2D

No 19

Format

voidMTH_Pers2D(MthXyz *p3d, MthXy *unitPixel, XyInt *p2d)

input

p3d	: Viewpoint coordinate system 3D vertex coordinates
unitPixel	:Unit pixel number of screen XY

output

p2d: Screen 2D coordinates after perspective transformation

function value

none

function

Set the screen at -1.0 with the origin of the viewpoint coordinate system as the viewpoint and perform perspective transformation from 3D to 2D. On the screen, a size of 1.0 corresponds to the number of unit pixels on the screen XY.

＜ Random number generation process＞

one View table

Title function specification

Function Initializing random number generation

Function name MTH_InitialRand

No 20

Format

void MTH_InitialRand(Uint32 initVal)

input

initVal: Initial parameter value for random number generation

output

none

function value

none

function

Set the initial parameters for calculating the random number returned by MTH_GetRand. If this initialization routine is not called, the initial parameter value for random number calculation will be 0.

one View table

Title function specification

Function return random value

Function name MTH_GetRand

No 21

Format

Uint32 randVal = MTH_GetRand(void)

input

none

output

none

function value

randVal: Random value from 0x00000000 to 0xffffffff

function

Returns a random value each time it is called.

＜ Spline curve calculation process＞

one View table

Title function specification

Function Curve calculation work area definition macro

Function name MTH_INIT_CURVE

No 22

Format

MTH_INIT_CURVEWORK(WORK_AREA, POINT_MAX)

input

WORK_AREA	:Work area name
POINT_MAX	: Maximum number of input points

function

Define the work area required to execute the curve calculation function in the user area.
Pass the pointer of this definition area to each curve calculation function as a parameter.
The secured capacity is the maximum number of input points x 36 bytes.
The number of output coordinates is (in_n−1)*step+1, so please prepare an array larger than that.

one View table

Title function specification

Function 2D

Function name MTH_Curve2

No 23

Format

Unit32 count = MTH_Curve2 (MthCurveWork *work, MthXy *in_aray,Unit32 in_n, Unit32 out_n, MthXy *out_aray)

input

work	: Work area pointer
in_aray	: input coordinate array
in_n	: Number of input coordinates
out_n	: Number of output coordinates

output

out_aray: Output coordinate array

function value

count: Number of output coordinates greater than or equal to 2 0: Parameter error

function

work specifies the work area secured with the MTH_INIT_CURVE macro.
in_aray specifies a pointer to an array of input coordinates to pass through the curve.
in_n specifies the number of in_aray. Please specify a value of 3 or more.
out_n specifies the number of out_aray. Please specify a value of 2 or more.
out_aray is a pointer that receives the calculation result. An array of output coordinates passing through the curve is returned.

one View table

Title function specification

Function with 2D tangent

Function name MTH_Curve2t

No 24

Format

Unit32 count=MTH_Curve2t(MthCurveWork *work, MthXy *in_aray,Unit32 in_n,Unit32 out_n, MthXy *out_aray, MthXy *tan_aray)

input

work	: Work area pointer
in_aray	: input coordinate array
in_n	: Number of input coordinates
out_n	: Number of output coordinates

output

out_aray	:Output coordinate array
tan_aray	: Tangent vector of each output coordinate

function value

count: Number of output coordinates greater than or equal to 2 0: Parameter error

function

work specifies the work area secured with the MTH_INIT_CURVE macro.
in_aray specifies a pointer to an array of input coordinates to pass through the curve.
in_n specifies the number of in_aray. Please specify a value of 3 or more.
out_n specifies the number of out_aray. Please specify a value of 2 or more.
out_aray is a pointer that receives the calculation result. An array of output coordinates passing through the curve is returned.
tan_aray returns a tangent vector indicating the direction of travel at each output coordinate. The magnitude of the tangent vector is 1.0.

one View table

Title function specification

Function three dimensional

Function name MTH_Curve3

No 25

Format

Unit32 count = MTH_Curve3(MthCurveWork *work, MthXyz *in_aray,Unit32 in_n,Unit32 out_n, MthXyz *out_aray)

input

work	: Work area pointer
in_aray	: input coordinate array
in_n	: Number of input coordinates
out_n	: Number of output coordinates

output

out_aray: Output coordinate array

function value

count: Number of output coordinates greater than or equal to 2 0: Parameter error

function

work specifies the work area secured with the MTH_INIT_CURVE macro.
in_aray specifies a pointer to an array of input coordinates to pass through the curve.
in_n specifies the number of in_aray. Please specify a value of 3 or more.
out_n specifies the number of out_aray. Please specify a value of 2 or more.
out_aray is a pointer that receives the calculation result. An array of output coordinates passing through the curve is returned.

one View table

Title function specification

Function with 3D tangent

Function name MTH_Curve3t

No 26

Format

Unit32 count = MTH_Curve3t(MthCurveWork *work, MthXyz *in_aray,Unit32 in_n, Unit32 out_n, MthXyz *out_aray, MthXyz *tan_aray)

input

work: Pointer to work area in_aray: Input coordinate array in_n: Number of input coordinates out_n: Number of output coordinates

output

out_aray	:Output coordinate array
tan_aray	: Tangent vector of each output coordinate

function value

count: Number of output coordinates greater than or equal to 2 0: Parameter error

function

work specifies the work area secured with the MTH_INIT_CURVE macro.
in_aray specifies a pointer to an array of input coordinates to pass through the curve.
in_n specifies the number of in_aray. Please specify a value of 3 or more.
out_n specifies the number of out_aray. Please specify a value of 2 or more.
out_aray is a pointer that receives the calculation result. An array of output coordinates passing through the curve is returned.
tan_aray returns a tangent vector indicating the direction of travel at each output coordinate. The magnitude of the tangent vector is 1.0.

Precautions for use

These curve calculation functions are developed with priority given to processing speed, so no overflow check is performed. However, since these functions handle large values during operation, overflow may occur. Acceptable ranges for input data are:

• Distance between points is 0.1 or more
• Point coordinates range from −1000 to 1000

Also, due to algorithm changes in future version updates, the same output coordinates may not be returned even if the input parameters are the same.

＜ Fixed-point arithmetic＞

one View table

Title function specification

Function multiplication routine

Function name MTH_Mul

No 27

Format

Fixed32 result = MTH_Mul(Fixed32 a, Fixed32 b)

input

a	:multiplicand
b	:multiplier

output

none

function value

result: Multiplication result

function

Performs fixed-point multiplication processing.

one View table

Title function specification

Function division routine

Function name MTH_Div

No 28

Format

Fixed32 result = MTH_Div(Fixed32 a, Fixed32 b)

input

a	:dividend
b	:divisor

output

none

function value

result: division result

function

Performs fixed-point division processing.

one View table

Title function specification

Function Fixed point → floating point type conversion macro

Function name MTH_FLOAT

No 29

Format

float b = MTH_FLOAT(Fixed32 a)

input

a: Fixed-point data

output

none

function value

b: Result of type conversion to floating point

function

Type conversion macro from fixed point to floating point format.

one View table

Title function specification

Function Floating point → fixed point type conversion macro

Function name MTH_FIXED

No 30

Format

Fixed32 b = MTH_FIXED(float a)

input

a: Floating point data

output

none

function value

b: Result of type conversion to fixed point

function

Type conversion macro from floating point to fixed point format.

one View table

Title function specification

Function Integer → Fixed-point type conversion routine

Function name MTH_IntToFixed

No 31

Format

Fixed32 b = MTH_IntToFixed(Sint32 a);

input

a: Integer data

output

none

function value

b: Result of type conversion to fixed point

function

Performs type conversion from integer to fixed-point format.

one View table

Title function specification

Function Fixed-point to integer type conversion routine

Function name MTH_FixedToInt

No 32

Format

Sint32 b = MTH_FixedToInt(Fixed a)

input

a: Fixed-point data

output

none

function value

b: Result of type conversion to integer

function

Performs type conversion from fixed-point to integer format.

one View table

Title function specification

Function Ternary product-sum operation

Function name MTH_Product

No 33

Format

Fixed32 result = MTH_Product(Fixed32 *a, Fixed32 *b)

input

a	: 3 multiplicand data strings
b	: 3 multiplier data strings

output

none

function value

result: product-sum operation result

function

Perform the calculation result = a[0] * b[0] + a[1] * b[1] + a[2] * b[2].

＜ Other functions＞

one View table

Title function specification

Function Square root calculation

Function name MTH_Sqrt

No 34

Format

Fixed32 result = MTH_Sqrt(Fixed32x)

input

x: Positive fixed-point real value

output

none

function value

result: calculated value of square root

function

Calculates and returns the square root of the input value.

one View table

Title function specification

Function length of the hypotenuse of a right triangle

Function name MTH_Hypot

No 35

Format

Fixed32 z = MTH_Hypot(Fixed32 x, Fixed32 y)

input

x	: horizontal side of right triangle
y	: vertical side of right triangle

output

none

function value

z: length of the hypotenuse of a right triangle

function

Returns z that satisfies the following formula.
z squared = x squared + y squared and z≧0

one View table

Title function specification

Function Surface normal vector calculation

Function name MTH_ComputeNormVect

No 36

Format

voidMTH_ComputeNormVect(Fixed32 surfNormK,MthXyz *p0,MthXyz *p1, MthXyz *p3, MthXyz *normal)

input

surfNormK	: Correction value of distance between vertices
p0	: Coordinates of the first clockwise vertex on the surface
p1	: Coordinates of the second clockwise vertex on the surface
p2	: Coordinates of the third clockwise vertex on the surface

output

normal: Normal vector of the surface (unit vector)

function value

none

function

Calculates the normal to the face of the specified clockwise vertex. The direction of the normal vector with respect to the surface is the opposite direction of the right-hand thread.
To calculate the normal vector, obtain two vectors based on the difference between two of the three vertices of the surface, and then calculate the cross product.
The specified correction value for the distance between vertices is converted into an absolute value and multiplied by two vectors to obtain the cross product. This is because if the distance between the three vertices of a surface is too small or too large, 32-bit fixed-point arithmetic may cause underflow or overflow in the cross product calculation, making it impossible to calculate correctly.
To avoid this, when the vector is calculated based on the difference between the three vertices of the surface, set the correction value for the distance between the vertices so that the absolute value of the vector is as close to 1.0 as possible.
If the sign of the correction value for the distance between vertices is negative, the normal vector will be in the opposite direction.