2.3 Function specifications

<Trigonometric function>

List

Title Function specifications

Function sin function

Function Name MTH_Sin

No 1

Form

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 for the specified angle.

List	Title Function specifications	Function cos function	Function Name MTH_Cos	No 2

Form

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 for the specified angle.

List

Title Function specifications

Function atan function

Function Name MTH_Atan

No 3

Form

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>

List

Title Function specifications

Function Matrix table initialization

Function Name MTH_InitialMatrix

No Four

Form

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

input

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

output

matrixTbl: Matrix table

Function value

none

function

Initialize the matrix table.

List

Title Function specifications

Function Clear current matrix

Function Name MTH_ClearMatrix

No Five

Form

void MTH_ClearMatrix (MthMatrixTbl * matrixTbl)

input

matrixTbl: Matrix table

output

none

Function value

none

function

Clears the current matrix in the matrix stack into an identity matrix.

List

Title Function specifications

Function Matrix push

Function Name MTH_PushMatrix

No 6

Form

void MTH_PushMatrix (MthMatrixTbl * matrixTbl)

input

matrixTbl: Matrix table

output

none

Function value

none

function

Push the current matrix.

List

Title Function specifications

Function Matrix pop

Function Name MTH_PopMatrix

No 7

Form

void MTH_PopMatrix (MthMatrixTbl * matrixTbl)

input

matrixTbl: Matrix table

output

none

Function value

none

function

Pop the current matrix.

List

Title Function specifications

Function Matrix synthesis / translation

Function Name MTH_MoveMatrix

No 8

Form

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

input

matrixTbl	: Matrix table
x	: Movement amount 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 XYZ translation matrix composition with respect to the current matrix.

List

Title Function specifications

Function Matrix synthesis / X-axis rotation

Function Name MTH_RotateMatrixX

No 9

Form

void MTH_RotateMatrixX (MthMatrixTbl * matrixTbl, Fixed32 x Degree)

input

matrixTbl	: Matrix table
xDegree	: X-axis rotation angle (range -180 to 180)

output

none

Function value

none

function

Performs matrix composition of X-axis rotation with respect to the current matrix.

List

Title Function specifications

Function Matrix synthesis / Y-axis rotation

Function Name MTH_RotateMatrixY

No Ten

Form

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

Y-axis rotation matrix composition is performed for the current matrix.

List

Title Function specifications

Function Matrix synthesis / Z-axis rotation

Function Name MTH_RotateMatrixZ

No 11

Form

void MTH_RotateMatrixZ (MthMatrixTbl * matrixTbl, Fixed32 zDegree)

input

matrixTbl	: Matrix table
zDegree	: Z-axis rotation angle (range -180 to 180)

output

none

Function value

none

function

Performs matrix composition of Z-axis rotation with respect to the current matrix.

List

Title Function specifications

Function Matrix synthesis / Z-axis code inversion

Function Name MTH_ReverseZ

No 12

Form

void MTH_ReverseZ (MthMatrixTbl * matrixTbl)

input

matrixTbl: Matrix table

output

none

Function value

none

function

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

List

Title Function specifications

Function Matrix calculation / multiplication

Function Name MTH_MulMatrix

No 13

Form

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 the matrix a and b and output to c.

List

Title Function specifications

Function Matrix calculation / vertex coordinate transformation

Function Name MTH_CordTrans

No 14

Form

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

input

matrix	: Conversion matrix
src	: Pre-conversion vertex coordinates

output

ans: Converted vertex coordinates

Function value

none

function

The coordinates of the vertices are converted by the conversion matrix.

List

Title Function specifications

Function Matrix calculation / normal vector coordinate transformation

Function Name MTH_NormalTrans

No 15

Form

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

input

matrix	: Conversion Matrick
src	: Pre-conversion normal vector

output

ans: Converted normal vector

Function value

none

function

Coordinates of the normal vector are transformed by the transformation matrix.

<3D polygon data coordinate conversion processing by DSP>

List

Title Function specifications

Function Initialization of coordinate conversion process

Function Name MTH_PolyDataTransInit

No 16

Form

void MTH_PolyDataTransInit (void)

input

none

output

none

Function value

none

function

Loads the DSP initialization and coordinate conversion processing program.

List

Title Function specifications

Function Coordinate transformation of 3D polygon data

Function Name MTH_PolyDataTransExec

No 17

Form

void MTH_PolyDataTransExec (MthPolyTransParm * polyTransParm)

input

polyTransParm: Coordinate transformation parameter table

output

polyTransParm: The following area of the coordinate conversion parameter table is output.

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

Function value

none

function

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

・ Hidden surface determination and brightness calculation of polygon surface

-Related parameter items-
<Input> surfCount Number of polygon faces surfPoint Representative point table of polygon faces for face brightness calculation surfNormal Polygon face normal table matrix Conversion matrix to viewpoint coordinate system lightVector Light source vector in viewpoint coordinate system <Output> surfBright Polygon face brightness Calculation result table bit31 bit0
           o ... .... .... .... .... .... ... o oooo 
           | | ||||
           | +-++++ ---- Brightness 
           0x00: Darkest | 0x1f: Brightest + --------- 1: Hidden surface 0: Display surface

-Conversion process of vertices to viewpoint coordinate system

-Related parameter items-
<Input> transViewVertCount Number of vertex entries for viewpoint coordinate conversion transViewVertSrc Perm data table before viewpoint coordinate conversion viewMatrix Conversion matrix to viewpoint coordinate system <Output> transViewVertAns Vertex data table after viewpoint coordinate conversion

・ Luminance calculation of vertices for gourd display (optional)

-Related parameter items-
<Input> gourVertCount When the number of vertex entries in the vertex brightness calculation is 0, the vertex brightness is not calculated. VertNormal Vertex normal table matrix for vertex brightness calculation Conversion matrix to the viewpoint coordinate system lightVector Light source vector in the viewpoint coordinate system < Output> vertBright Vertex brightness calculation result table 0x00 = darkest 0x1f = brightest

-Conversion process of vertices to world coordinate system

-Related parameter items-
<Input> transWorldVertCount When the number of vertex entries for world coordinate conversion = 0, the world coordinate system of the vertices is not converted. Coordinate data table 

List

Title Function specifications

Function Completion check of coordinate conversion process

Function Name MTH_PolyDataTransCheck

No 18

Form

voidMTH_PolyDataTransCheck (void)

input

none

output

none

Function value

none

function

Wait until the coordinate conversion process by the DSP is completed.

<Perspective conversion processing>

List

Title Function specifications

Function Perspective transformation of 3D points

Function Name MTH_Pers2D

No 19

Form

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

input

p3d	: Viewpoint coordinate system 3D vertex coordinates
unitPixel	: Number of pixels per unit of screen XY

output

p2d: Screen 2D coordinates after perspective conversion

Function value

none

function

Set the screen at -1.0 with the origin of the viewpoint coordinate system as the viewpoint to perform fluoroscopic conversion from 3D to 2D. A size of 1.0 on the screen corresponds to the number of pixels per unit of screen XY.

<Random number generation processing>

List

Title Function specifications

Function Initialization of random number generation

Function Name MTH_InitialRand

No 20

Form

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 numbers returned by MTH_GetRand. If this initialization routine is not called, the initial parameter value for random number calculation is 0.

List

Title Function specifications

Function Returns a random number

Function Name MTH_GetRand

No twenty one

Form

Uint32 randVal = MTH_GetRand (void)

input

none

output

none

Function value

randVal: Random value from 0x00000000 to 0xffffffff

function

Returns a random number each time it is called.

<Spline curve calculation processing>

List

Title Function specifications

Function Curve calculation work area definition macro

Function Name MTH_INIT_CURVE

No twenty two

Form

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 a pointer to this definition area as a parameter to each curve calculation function.
The reserved capacity is the maximum number of input points x 36 bytes.
The number of output coordinates is (in_n−1) * step + 1, so prepare an array with a larger size.

List

Title Function specifications

Function 2D

Function Name MTH_Curve2

No twenty three

Form

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 of 2 or more 0: Parameter error

function

work specifies the work area allocated by 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. Specify a value of 3 or more.
out_n specifies the number of out_aray. Specify a value of 2 or more.
out_aray is a pointer that receives the calculation result. Returns an array of output coordinates that traverse the curve.

List

Title Function specifications

Function With 2D tangent

Function Name MTH_Curve2t

No twenty four

Form

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 of 2 or more 0: Parameter error

function

work specifies the work area allocated by 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. Specify a value of 3 or more.
out_n specifies the number of out_aray. Specify a value of 2 or more.
out_aray is a pointer that receives the calculation result. Returns an array of output coordinates that traverse the curve.
tan_aray returns a tangent vector that indicates the direction of travel at each output coordinate. The magnitude of the tangent vector is 1.0.

List

Title Function specifications

Function 3D

Function Name MTH_Curve3

No twenty five

Form

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 of 2 or more 0: Parameter error

function

work specifies the work area allocated by 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. Specify a value of 3 or more.
out_n specifies the number of out_aray. Specify a value of 2 or more.
out_aray is a pointer that receives the calculation result. Returns an array of output coordinates that traverse the curve.

List

Title Function specifications

Function With 3D tangent

Function Name MTH_Curve3t

No 26

Form

Unit32 count = MTH_Curve3t (MthCurveWork * work, MthXyz * in_aray, Unit32 in_n, Unit32 out_n, MthXyz * out_aray, MthXyz * 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 of 2 or more 0: Parameter error

function

work specifies the work area allocated by 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. Specify a value of 3 or more.
out_n specifies the number of out_aray. Specify a value of 2 or more.
out_aray is a pointer that receives the calculation result. Returns an array of output coordinates that traverse the curve.
tan_aray returns a tangent vector that indicates 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 on processing speed, so overflow checking is not performed. However, these functions handle large values in the middle of the operation and can overflow. The allowable range of input data is as follows.

• Distance between points is 0.1 or more
• Point coordinate values range from -1000 to 1000

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

<Fixed point arithmetic>

List

Title Function specifications

Function Multiplication routine

Function Name MTH_Mul

No 27

Form

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.

List

Title Function specifications

Function Division routine

Function Name MTH_Div

No 28

Form

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.

List

Title Function specifications

Function Fixed-point to floating-point conversion macro

Function Name MTH_FLOAT

No 29

Form

float b = MTH_FLOAT (Fixed32 a)

input

a: Fixed-point data

output

none

Function value

b: Type conversion result to floating point

function

A type conversion macro from fixed-point to floating-point format.

List

Title Function specifications

Function Floating point to fixed point type conversion macro

Function Name MTH_FIXED

No 30

Form

Fixed32 b = MTH_FIXED (float a)

input

a: Floating point data

output

none

Function value

b: Type conversion result to fixed point

function

A type conversion macro from floating point to fixed point format.

List

Title Function specifications

Function Integer to fixed-point type conversion routine

Function Name MTH_IntToFixed

No 31

Form

Fixed32 b = MTH_IntToFixed (Sint32 a);

input

a: Integer data

output

none

Function value

b: Type conversion result to fixed point

function

Performs type conversion processing from integer to fixed-point format.

List

Title Function specifications

Function Fixed-point to integer type conversion routine

Function Name MTH_FixedToInt

No 32

Form

Sint32 b = MTH_FixedToInt (Fixed a)

input

a: Fixed-point data

output

none

Function value

b: Type conversion result to integer

function

Performs type conversion processing from fixed point to integer format.

List

Title Function specifications

Function Three-term multiply-accumulate operation

Function Name MTH_Product

No 33

Form

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

result = a [0] * b [0] + a [1] * b [1] + a [2] * b [2] is processed.

<Other functions>

List

Title Function specifications

Function Square root calculation

Function Name MTH_Sqrt

No 34

Form

Fixed32 result = MTH_Sqrt (Fixed32x)

input

x: Positive fixed-point real number

output

none

Function value

result: Calculated square root

function

Calculates and returns the square root of the input value.

List

Title Function specifications

Function The length of the hypotenuse of a right triangle

Function Name MTH_Hypot

No 35

Form

Fixed32 z = MTH_Hypot (Fixed32 x, Fixed32 y)

input

x	: Horizontal side of a right triangle
y	: Vertical side of a right triangle

output

none

Function value

z: Length of the hypotenuse of a right triangle

function

Returns z that satisfies the following equation.
z squared = x squared + y squared and z ≥ 0

List

Title Function specifications

Function Face normal vector calculation

Function Name MTH_ComputeNormVect

No 36

Form

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 rotation on the surface
p1	: Coordinates of the second clockwise rotation on the surface
p2	: Coordinates of the third clockwise rotation on the surface

output

normal: surface normal vector (unit vector)

Function value

none

function

Calculates the normal for the face of the specified clockwise vertex. The direction of the normal vector with respect to the plane is the opposite of the right-hand thread.
The normal vector is calculated by obtaining two vectors based on the difference between two of the three vertices of the surface and the outer product.
The correction value of the specified inter-vertex distance is absoluteized and multiplied by two vectors for finding the outer product. This is because if the space 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 outer product calculation and may not be calculated correctly.
To avoid this, set the correction value of the inter-vertex distance so that the absolute value of the vector is as close to 1.0 as possible at the stage of obtaining the vector by the difference between the three vertices of the surface.
If the sign of the correction value of the distance between vertices is negative, the normal vector is reversed.