Copyright: Raymond Filiatreault retains all copyright to the library, the source code for the modules, and this Help file. December 2002.
Citation: Prepared by Raymond Filiatreault.


FpuLib v2.1 Help

Revised January 2005

Introduction

Design Philosophy

Sources of Errors

Available Functions

FPU Constants

Example

Legal

Acknowledgement


Introduction

This library contains functions to perform high precision floating point computations with the FPU coprocessor, without the need to learn all the intricacies of the coding syntax and limitations of the FPU. The obvious drawback is some code overhead to decipher the meaning of parameters. In most cases however, the speed should not be affected significantly when compared to directly programming the FPU.

Original release. December 2002 as Fpulib.

Modified January 2004 to free all registers required by the function to avoid any potential FPU stack overflow.

Modified March 2004 to preserve all FPU registers while avoiding any stack overflow. Also corrected a minor flaw in the FpuSize function and added the FpuState function.

Modified January 2005 to trash the FPU’s ST(7) data register whenever necessary to prevent reporting an error if a register is not available for returning a result on the FPU.


Design Philosophy

The philosophy adopted for the design of the library was to make it as flexible as possible without making it overly complex and/or cumbersome.

Only REAL10 (80-bit) numbers are allowed as floating point numbers. The reasoning was that the FPU performs all its operations strictly on 80-bit numbers. Any other type of number used by the FPU is first converted to the 80-bit format. Therefore there is no major advantage in FPU speed performance in using SHORT REAL (32-bit) or LONG REAL (64-bit) floating point numbers. The only real disadvantage is a minimal increase in memory storage requirements.

Only LONG (32-bit) signed integers (DWORD) are allowed for operations with the library functions. Although SHORT integers (WORD) could be allowed with some FPU instructions, they can be easily sign extended for the purpose of these functions. However, although only values from memory can be retrieved by the FPU, the functions were designed to directly accept integer values (either immediate or CPU register content) as input where integers may be used.

There are two widely used constants (B and e) which are made available as input parameters in all functions where they may be used.

Unless a source parameter was specified as being in the TOP data register, the original Fpulib was designed to initialize the FPU to prevent any potential “stack overflow”. This destroyed any data which may have been present in the other FPU registers. This was revised later to destroy only the data (if any) in the registers which were necessary to perform the function. This new version will not destroy any of the existing data, except possibly the data in the ST(7) register.

Whenever a result is specified to be returned on the FPU, it would replace a source parameter which would have been identified as having been in the TOP data register. If no source is identified as being on the FPU, its ST7 data register must then be free if the result must be returned on the FPU. Otherwise, the function will trash that register in order to free it for the returned value.

Whenever a result is specified to be returned to a memory location, any source parameter identified as having been on the FPU may or may not be preserved. See the description of each function. (As a general guide, such source would not be preserved when used for a computation.)

The only function which performs a thorough checking of the input is the one for converting an alphanumeric decimal string to a REAL10 number. None of the other functions verify the adequacy of the input. If a source parameter is not identified or if the FPU reports an invalid operation, EAX is simply returned with zero indicating an error. No error description is provided.

See also Sources of Errors.


Sources of Errors

Errors in the use of these library functions are all reported by returning 0 in EAX. It is the user’s responsibility to verify this return code to avoid a proliferation of errors whenever in doubt. The types of errors are too numerous to provide more specific error codes or messages.

Some of the potential errors are listed below. That list must not be considered as exhaustive considering the complexity of the library and other external factors. Passed parameters must be accepted as is by the functions because of the impossibility of type checking.

The following errors will generate an immediate error code within the function.

A source parameter is identified as being on the FPU but the FPU’s TOP data register is empty.

A source parameter is identified as a type not allowed by the function.

An 80-bit REAL source parameter is not considered by the FPU as being a valid one.

A negative number is used as a parameter for a function which only allows a positive number for that parameter.

A source parameter has a value outside the range allowable by the function.

Some other errors may not immediately return the error code in EAX but the returned result would be erroneous, possibly generating the error code with other functions when used as a parameter.

Dividing by 0 does NOT return the error code but the result is a special valid number treated by the FPU as equal to infinity. Using that result as a source parameter for other functions may then result in the error code being generated.

A source parameter is identified as being an 80-bit REAL number or a 32-bit integer at the specified memory address but a different type resides at that address (while still being considered as acceptable data by the FPU). The erroneous result could thus be propagated through other functions without ever generating the error code.


Functions
Available Functions

Conversion Functions

FpuAtoFL	Converts a decimal string to a REAL10 number

FpuFLtoA	Converts a REAL10 number to a decimal string

Arithmetic Functions

FpuAdd	Adds two numbers

FpuSub	Subtracts one number from another

FpuMul	Multiplies one number by another

FpuDiv	Divides one number by another

FpuSqrt	Extracts the square root of a positive number

FpuXexpY	Raises a positive number by an exponent

FpuAbs	Returns the absolute value of a number

FpuChs	Changes the sign of a number

FpuRound	Rounds a number to the nearest integer

FpuTrunc	Discards the decimal portion of a number

Logarithmic Functions

FpuLogx	Returns the base 10 logarithm of a positive number

FpuLnx	Returns the Napierian logarithm of a positive number

FpuTexpX	Returns the number 10 raised to a power (common antilog)

FpuEexpX	Returns the Napierian constant e raised to a power (Napierian antilog)

Trigonometric Functions

FpuSin	Returns the sine of an angle

FpuCos	Returns the cosine of an angle

FpuTan	Returns the tangent of an angle

FpuArcsin	Returns the angle corresponding to a sine value

FpuArccos	Returns the angle corresponding to a cosine value

FpuArctan	Returns the angle corresponding to a tangent value

Hyperbolic Functions

FpuSinh	Returns the hyperbolic sine of a number

FpuCosh	Returns the hyperbolic cosine of a number

FpuTanh	Returns the hyperbolic tangent of a number

FpuArcsinh	Returns the number corresponding to a hyperbolic sine

FpuArccosh	Returns the number corresponding to a hyperbolic cosine

FpuArctanh	Returns the number corresponding to a hyperbolic tangent

Miscellaneous Functions

FpuSize	Returns the exponent of scientific notation

FpuComp	Compares two numbers

FpuExam	Checks REAL10 for its validity, its sign, a value of zero, an absolute value less than 1, and/or a value of infinity

FpuState	Returns a null-terminated string listing the content of the FPU registers


FpuAtoFL

The FpuAtoFL converts an alphanumeric decimal string to an 80-bit REAL number.

 FpuAtoFL (

lpszSrc	//pointer to a null-terminated string

lpDest	//pointer to destination of result

uID	//ID flag for destination

)

 Parameters

lpszSrc

This points to the null-terminated alphanumeric decimal representation of the number. Leading spaces are disregarded. The string can be in regular notation or in scientific notation. Characters other than those allowed between the leading sign or leading digit and the terminating zero will return an immediate error. A maximum of 18 digits (excluding all leading 0's and trailing decimal 0's, and excluding the digits of the exponent in scientific notation) is permitted. The only permitted decimal delimiter is the period (“.”) but is not a necessity for integer values. Decimal digits are not a necessity either. The exponent in scientific notation can be preceded with “e” or “E”. That exponent must be within the +/-4931 range. The “+” sign is not necessary for positive exponents.

lpDest

This points to a TBYTE where the 80-bit REAL result of the conversion will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the DEST_? flags needs to be indicated.

uID Flag	Meaning

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified destination will not be modified.

If the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Example:

invoke FpuAtoFL, ADDR Src, 0, DEST_FPU

In this example, the alphanumeric decimal number pointed to by the memory variable labeled Src is converted to an 80-bit REAL number and returned on the FPU.


FpuFLtoA

The FpuFLtoA function converts an 80-bit REAL number to its alphanumeric decimal representation (either in decimal format or scientific notation) and returns the result as a null-terminated string at the specified destination.

 FpuFLtoA (

lpSrc1	//pointer to an 80-bit REAL number

lpSrc2	//pointer to, or value of, number of decimal digits to return

lpszDest	//pointer to destination of result

uID	//ID flags for sources and format

)

 Parameters

lpSrc1

This points to an 80-bit REAL number. (This parameter is ignored if uID indicates that the value is already on the FPU.)

LpSrc2

This either points to a DWORD integer in memory, or is an immediate DWORD integer according to the content of uID.

The low byte of the low word of the integer indicates the number of decimal digits to be returned in the result. The total number of integer digits and decimal digits cannot exceed 16. Otherwise, the number of decimal digits will be reduced accordingly. (Note that at least one integer digit is always returned.)

The high byte of the low word of the integer indicates the number of characters before the decimal point, spaces being used for padding. This number cannot exceed 17 (16 digits + sign); it would otherwise be reduced to 17. (This byte is ignored if uID indicates that the result must be returned in the scientific format.)

The high word of this parameter is ignored.

lpszDest

This points to a memory location where the result will be returned. It must be large enough to hold the number of characters returned. At most, it may have 17 characters before the decimal point, one decimal point, 15 decimal digits, and the terminating zero (for a maximum of 34 characters).

uID

One of the SRC1_? flags must be OR'ed with only one of the SRC2_? flags and OR’ed with one of the STR_? flags. (The STR_REG flag does not need to be OR’ed if the string must be returned in decimal format; that is the default.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

SRC2_DMEM	Src2 is a pointer to a 32-bit unsigned integer

SRC2_DIMM	Src2 is a 32-bit unsigned integer

STR_REG	The string must be returned in regular decimal format

STR_SCI	The string must be returned in scientific notation

 Return Values:

If the source is considered a valid REAL number, the converted string will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the null-terminated string ERROR will be placed at the specified destination.

The source is never modified, whether it is in memory or on the FPU.

If the number is greater than or equal to 10^16, the result will be returned in scientific notation (with the specified number of decimals) regardless of the STR flag. If the number is equal to zero, it is simply returned as an ASCII “0" and a terminating zero regardless of the STR flag.

All the FPU registers and all the CPU registers (except EAX) are preserved.

 Example:

invoke FpuFLtoA, 0, 4, ADDR Dest, SRC1_FPU or SRC2_DIMM

In this example, the 80-bit REAL number is taken from the FPU (ignoring the 1st parameter) and the null-terminated alphanumeric decimal string is written in regular decimal format with 4 decimal digits at the destination identified as the memory variable labeled Dest.


FpuAdd

The FpuAdd function adds two numbers and returns the result as an 80-bit REAL number at the specified destination.

Src1 + Src2 Y Dest

 FpuAdd (

lpSrc1	//pointer to, or value of, 1st parameter

lpSrc2	//pointer to, or value of, 2nd parameter

lpDest	//pointer to destination of result

uID	//ID flags for sources and destination

)

 Parameters

lpSrc1

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER (see FPU Constants for description),

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpSrc2

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER,

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL result of the addition will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with only one of the SRC2_? flags and OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src1 is already on the FPU

SRC1_REAL	Src1 is a pointer to an 80-bit REAL number

SRC1_DMEM	Src1 is a pointer to a 32-bit signed integer

SRC1_DIMM	Src1 is a 32-bit signed integer

SRC1_CONST	Src1 is one of the special FPU constants

SRC2_FPU	Src2 is already on the FPU

SRC2_REAL	Src2 is a pointer to an 80-bit REAL number

SRC2_DMEM	Src2 is a pointer to a 32-bit signed integer

SRC2_DIMM	Src2 is a 32-bit signed integer

SRC2_CONST	Src2 is one of the special FPU constants

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified sources and destination will not be modified.

When a source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If no source is from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

Because these library functions allow only one value to be accessed from the FPU, identifying both sources as being from the FPU will result in adding that FPU value to itself.

 Example:

invoke FpuAdd, ADDR Src1, eax, ADDR Dest, SRC1_REAL or SRC2_DIMM

In this example, the 80-bit REAL number from the TBYTE memory variable labeled Src1 is added with the DWORD integer in EAX, and the result is transferred as an 80-bit REAL to the TBYTE memory variable labeled Dest. All the FPU registers are preserved.


FpuSub

The FpuSub function subtracts the second parameter from the first one and returns the result as an 80-bit REAL number at the specified destination.

Src1 - Src2 Y Dest

 FpuSub (

lpSrc1	//pointer to, or value of, 1st parameter

lpSrc2	//pointer to, or value of, 2nd parameter

lpDest	//pointer to destination of result

uID	//ID flags for sources and destination

)

 Parameters

lpSrc1

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER, (see FPU Constants for description),

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpSrc2

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER,

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

 lpDest

This points to a TBYTE where the 80-bit REAL result of the subtraction will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with only one of the SRC2_? flags and OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src1 is already on the FPU

SRC1_REAL	Src1 is a pointer to an 80-bit REAL number

SRC1_DMEM	Src1 is a pointer to a 32-bit signed integer

SRC1_DIMM	Src1 is a 32-bit signed integer

SRC1_CONST	Src1 is one of the special FPU constants

SRC2_FPU	Src2 is already on the FPU

SRC2_REAL	Src2 is a pointer to an 80-bit REAL number

SRC2_DMEM	Src2 is a pointer to a 32-bit signed integer

SRC2_DIMM	Src2 is a 32-bit signed integer

SRC2_CONST	Src2 is one of the special FPU constants

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified sources and destination will not be modified.

When a source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If no source is from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

Because these library functions allow only one value to be accessed from the FPU, identifying both sources as being on the FPU will result in subtracting the FPU value from itself, leaving 0 as the answer.

 Example:

invoke FpuSub, 0, 100, 0, SRC1_FPU or SRC2_DIMM or DEST_FPU

In this example, the 1st parameter is ignored because its value is identified as being on the FPU. Thus, 100 is subtracted from the 80-bit REAL number already on the FPU, and the result replaces the source parameter on the FPU, ignoring the 3rd parameter.


FpuMul

The FpuMul function multiplies two numbers and returns the result as an 80-bit REAL number at the specified destination.

Src1 x Src2 Y Dest

 FpuMul (

lpSrc1	//pointer to, or value of, 1st parameter

lpSrc2	//pointer to, or value of, 2nd parameter

lpDest	//pointer to destination of result

uID	//ID flags for sources and destination

)

 Parameters

lpSrc1

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER, (see FPU Constants for description),

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpSrc2

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER,

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

 lpDest

This points to a TBYTE where the 80-bit REAL result of the multiplication will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with only one of the SRC2_? flags and OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src1 is already on the FPU

SRC1_REAL	Src1 is a pointer to an 80-bit REAL number

SRC1_DMEM	Src1 is a pointer to a 32-bit signed integer

SRC1_DIMM	Src1 is a 32-bit signed integer

SRC1_CONST	Src1 is one of the special FPU constants

SRC2_FPU	Src2 is already on the FPU

SRC2_REAL	Src2 is a pointer to an 80-bit REAL number

SRC2_DMEM	Src2 is a pointer to a 32-bit signed integer

SRC2_DIMM	Src2 is a 32-bit signed integer

SRC2_CONST	Src2 is one of the special FPU constants

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified sources and destination will not be modified.

When a source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If no source is from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

Because these library functions allow only one value to be accessed from the FPU, identifying both sources as being on the FPU will result in multiplying that FPU value by itself. This may be occasionally useful.

 Example:

Assuming that the radius of a circle would be an 80-bit REAL number in the TBYTE memory variable labeled Radius, the following sequence would compute the area of the circle and return the result on the FPU:

invoke FpuMul, ADDR Radius, ADDR Radius, 0, SRC1_REAL or SRC2_REAL or DEST_FPU

invoke FpuMul, FPU_PI, 0, 0, SRC1_CONST or SRC2_FPU or DEST_FPU


FpuDiv

The FpuDiv function divides the first parameter by the second one and returns the result as an 80-bit REAL number at the specified destination.

Src1 ÷ Src2 Y Dest

 FpuDiv (

lpSrc1	//pointer to, or value of, 1st parameter

lpSrc2	//pointer to, or value of, 2nd parameter

lpDest	//pointer to destination of result

uID	//ID flags for sources and destination

)

 Parameters

lpSrc1

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER, (see FPU Constants for description),

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpSrc2

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER,

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

 lpDest

This points to a TBYTE where the 80-bit REAL result of the division will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with only one of the SRC2_? flags and OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src1 is already on the FPU

SRC1_REAL	Src1 is a pointer to an 80-bit REAL number

SRC1_DMEM	Src1 is a pointer to a 32-bit signed integer

SRC1_DIMM	Src1 is a 32-bit signed integer

SRC1_CONST	Src1 is one of the special FPU constants

SRC2_FPU	Src2 is already on the FPU

SRC2_REAL	Src2 is a pointer to an 80-bit REAL number

SRC2_DMEM	Src2 is a pointer to a 32-bit signed integer

SRC2_DIMM	Src2 is a 32-bit signed integer

SRC2_CONST	Src2 is one of the special FPU constants

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified sources and destination will not be modified.

When a source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If no source is from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

Because these library functions allow only one value to be accessed from the FPU, identifying both sources as being on the FPU will result in dividing that FPU value by itself, leaving 1 as the answer.

Dividing by zero is not considered an invalid operation and would NOT return the error code 0 in EAX. However, the result is a special FPU value interpreted as equal to infinity.

 Example:

invoke FpuDiv, 1, eax, ADDR Dest, SRC1_DIMM or SRC2_DIMM

In this example, the value of 1 is divided by the DWORD signed integer in EAX (yielding its reciprocal), and the result is transferred as an 80-bit REAL to the TBYTE memory variable labeled Dest. All FPU registers are preserved.


FpuSqrt

The FpuSqrt function extracts the square root of a positive number.

sqrt(Src) Y Dest

 FpuSqrt (

lpSrc	//pointer to, or value of, source parameter

lpDest	//pointer to destination of result

uID	//ID flags for source and destination

)

 Parameters

lpSrc

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER, (see FPU Constants for description),

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL result of the square root will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

SRC1_DMEM	Src is a pointer to a 32-bit signed integer

SRC1_DIMM	Src is a 32-bit signed integer

SRC1_CONST	Src is one of the special FPU constants

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

The source parameter MUST be a positive number. Trying to extract the square root of a negative number on the FPU would result in an invalid operation and the function will fail.

 Example:

invoke FpuSqrt, edx, 0, SRC1_DIMM or DEST_FPU

In this example, the square root of the 32-bit signed integer in EDX is extracted and the 80-bit REAL result is returned on the FPU (ignoring the 2nd parameter) if no error is reported.


FpuXexpY

The FpuXexpY function raises a positive number (first parameter) by an exponent (second parameter).

x^y Y Dest

 FpuXexpY (

lpSrc1	//pointer to, or value of, base parameter (x)

lpSrc2	//pointer to, or value of, exponent parameter (y)

lpDest	//pointer to destination of result

uID	//ID flags for sources and destination

)

 Parameters

lpSrc1

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER, (see FPU Constants for description),

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpSrc2

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER,

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL result of the function will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with only one of the SRC2_? flags and OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src1 is already on the FPU

SRC1_REAL	Src1 is a pointer to an 80-bit REAL number

SRC1_DMEM	Src1 is a pointer to a 32-bit signed integer

SRC1_DIMM	Src1 is a 32-bit signed integer

SRC1_CONST	Src1 is one of the special FPU constants

SRC2_FPU	Src2 is already on the FPU

SRC2_REAL	Src2 is a pointer to an 80-bit REAL number

SRC2_DMEM	Src2 is a pointer to a 32-bit signed integer

SRC2_DIMM	Src2 is a 32-bit signed integer

SRC2_CONST	Src2 is one of the special FPU constants

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified sources and destination will not be modified.

When a source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If no source is from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

The source base parameter MUST be a positive number. Trying to raise a negative number by an exponent would result in an invalid operation and the function will fail.

Very large (positive or negative) values of the source exponent may exceed the limits of the FPU and return a value of infinity. This would not be considered as an invalid operation and would not return the error code. However that return value may not be usable with other library functions.

Although the Napier constant e can be specified as the source for the base parameter, raising that constant to a power can also be performed with the FpuEexpX function.

 Example:

invoke FpuXexpY, ADDR Src1, 0, ADDR Dest, SRC1_REAL or SRC2_FPU

In this example, the base number is an 80-bit REAL identified by the TBYTE memory variable labeled Src1 and the exponent is already on the FPU (ignoring the 2nd parameter). The 80-bit REAL result is returned to the TBYTE memory variable labeled Dest and the source parameter on the FPU is removed if the function succeeds.


FpuAbs

|x| Y Dest

The FpuAbs function returns the absolute value of an 80-bit REAL number.

 FpuAbs (

lpSrc	//pointer to source parameter (x)

lpDest	//pointer to destination of result

uID	//ID flags for source and destination

)

 Parameters

lpSrc

This points to an 80-bit REAL number either in memory or on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL result will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

One of the SRC1_? flags must be OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the source is considered a valid REAL number, its absolute value will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

The source parameter MUST be an 80-bit REAL number. (The absolute value of integers can be easily obtained with CPU instructions.)

 Example:

invoke FpuAbs, 0, 0, SRC1_FPU or DEST_FPU

In this example, the 80-bit REAL number already on the FPU will be replaced by its absolute value if the function succeeds. (Both 1st and 2nd parameters are ignored.)


FpuTrunc

The FpuTrunc function returns the integer part of an 80-bit REAL number after discarding the fractional part.

 FpuTrunc (

lpSrc	//pointer to source parameter

lpDest	//pointer to destination of result

uID	//ID flags for source and destination

)

 Parameters

lpSrc

This points to an 80-bit REAL number either in memory or on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the result can be stored as an 80-bit REAL number or points to a DWORD where the result can be stored as a 32-bit LONG integer. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

One of the SRC1_? flags must be OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is a TBYTE in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

DEST_IMEM	lpDest is a pointer to a DWORD

 Return Values:

If the source is considered a valid REAL number, the result will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

The source parameter MUST be an 80-bit REAL number. (Integers are already truncated.)

 Example:

invoke FpuTrunc, ADDR Src, 0, SRC1_REAL or DEST_FPU

In this example, the source is an 80-bit REAL at memory variable labeled Scr and its truncated value will be returned as an 80-bit REAL number on the FPU (ignoring the 2nd parameter).


FpuRound

The FpuRound function rounds an 80-bit REAL number to its nearest integer value.

 FpuRound (

lpSrc	//pointer to source parameter

lpDest	//pointer to destination of result

uID	//ID flags for source and destination

)

 Parameters

lpSrc

This points to an 80-bit REAL number either in memory or on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the result can be stored as an 80-bit REAL number or points to a DWORD where the result can be stored as a 32-bit LONG integer. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

One of the SRC1_? flags must be OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is a TBYTE in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

DEST_IMEM    	lpDest is a pointer to a DWORD

 Return Values:

If the source is considered a valid REAL number, the result will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

The source parameter MUST be an 80-bit REAL number. (Integers are already rounded.)

 Example:

invoke FpuRound, 0, ADDR Dest, SRC1_FPU or DEST_IMEM

In this example, the 1st parameter is ignored and the 80-bit REAL number already on the FPU will be rounded to its nearest integer; the result will be stored as a 32-bit LONG integer at the DWORD memory variable labeled Dest and the source parameter will be removed from the FPU.


FpuChs

The FpuChs function changes the sign of an 80-bit REAL number.

-x Y Dest

 FpuChs (

lpSrc	//pointer to source parameter (x)

lpDest	//pointer to destination of result

uID	//ID flags for source and destination

)

 Parameters

lpSrc

This points to an 80-bit REAL number either in memory or on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL result will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

One of the SRC1_? flags must be OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the source is considered a valid REAL number, the result will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

The source parameter MUST be an 80-bit REAL number. (The sign of integers can be changed easily with CPU instructions.)

 Example:

invoke FpuChs, 0, ADDR Dest, SRC1_FPU

In this example, the 1st parameter is ignored and the sign of the 80-bit REAL value already on the FPU is changed; the result is stored at the TBYTE memory variable labeled Dest and the source parameter is removed from the FPU if the function succeeds.


FpuLnx

The FpuLnx function returns the natural (Napierian) logarithm of a positive non-zero number.

ln(x) Y Dest

 FpuLnx (

lpSrc	//pointer to, or value of, source parameter (x)

lpDest	//pointer to destination of result

uID	//ID flags for source and destination

)

 Parameters

lpSrc

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER, (see FPU Constants for description),

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL logarithm will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

SRC1_DMEM	Src is a pointer to a 32-bit signed integer

SRC1_DIMM	Src is a 32-bit signed integer

SRC1_CONST	Src is one of the special FPU constants

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

The source parameter MUST be a positive non-zero number. Negative or zero values will result in an invalid operation and the function will fail.

 Example:

invoke FpuLnx, eax, 0, SRC1_DIMM or DEST_FPU

In this example, the natural logarithm of the 32-bit signed integer in EAX is returned on the FPU as an 80-bit REAL value if the function succeeds. The 2nd parameter is ignored.


FpuLogx

The FpuLogx function returns the common (base 10) logarithm of a positive non-zero number.

log(x) Y Dest

 FpuLogx (

lpSrc	//pointer to, or value of, source parameter (x)

lpDest	//pointer to destination of result

uID	//ID flags for source and destination

)

 Parameters

lpSrc

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER (see FPU Constants for description),

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL logarithm will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

SRC1_DMEM	Src is a pointer to a 32-bit signed integer

SRC1_DIMM	Src is a 32-bit signed integer

SRC1_CONST	Src is one of the special FPU constants

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

The source parameter MUST be a positive non-zero number. Negative or zero values will result in an invalid operation and the function will fail.

 Example:

invoke FpuLogx, ADDR Src, 0, SRC1_REAL or DEST_FPU

In this example, the common (base 10) logarithm of the 80-bit REAL identified as the memory variable labeled Scr is computed and is returned on the FPU if the function succeeds. The second parameter is ignored.


FpuEexpX

The FpuEexpX function raises the Napierian constant e (2.71828...) by an exponent. (It could also be considered as returning the Napierian antilogarithm of a number.)

e^x Y Dest

 FpuEexpX (

lpSrc	//pointer to, or value of, exponent parameter (x)

lpDest	//pointer to destination of result

uID	//ID flags for source and destination

)

 Parameters

lpSrc

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER (see FPU Constants for description),

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL result will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

SRC1_DMEM	Src is a pointer to a 32-bit signed integer

SRC1_DIMM	Src is a 32-bit signed integer

SRC1_CONST	Src is one of the special FPU constants

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

Very large positive values of the source exponent may exceed the limits of the FPU and return a value of infinity. This would not be considered as an invalid operation and would not return the error code. However that return value may not be usable with other library functions.

 Example:

invoke FpuEexpX, 0, 0, SRC1_FPU or DEST_FPU

In this example, the Napierian constant e is raised by the exponent already on the FPU and the result is returned on the FPU replacing the source parameter if the function succeeds. Both 1st and 2nd parameters are ignored.


FpuTexpX

The FpuTexpX function raises the number 10 by an exponent. (It could also be considered as returning the common antilogarithm of a number.)

10^x Y Dest

 FpuTexpX (

lpSrc	//pointer to, or value of, source parameter (x)

lpDest	//pointer to destination of result

uID	//ID flags for source and destination

)

 Parameters

lpSrc

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER (see FPU Constants for description),

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL result will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

SRC1_DMEM	Src is a pointer to a 32-bit signed integer

SRC1_DIMM	Src is a 32-bit signed integer

SRC1_CONST	Src is one of the special FPU constants

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

Very large positive values of the source exponent may exceed the limits of the FPU and return a value of infinity. This would not be considered as an invalid operation and would not return the error code. However that return value may not be usable with other library functions.

 Example:

invoke FpuTexpX, ADDR Src, 0, SRC1_REAL or DEST_FPU

In this example, the number 10 is raised by the 80-bit REAL exponent located at the TBYTE memory variable labeled Scr and the result is returned on the FPU if the function succeeds. The 2nd parameter is ignored.


FpuSin

The FpuSin function returns the sine of an angle expressed in degrees or radians.

sin(x) Y Dest

 FpuSin (

lpSrc	//pointer to, or value of, angle (x)

lpDest	//pointer to destination of result

uID	//ID flags for source, angle type, and destination

)

 Parameters

lpSrc

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer, all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL sine value will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with one of the ANG_? Flags and OR’ed with one of the DEST_? flags. (The ANG flag does not need to be OR’ed if the angle is in degrees; that is the default type. The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

SRC1_DMEM	Src is a pointer to a 32-bit signed integer

SRC1_DIMM	Src is a 32-bit signed integer

ANG_RAD	The value of the angle is expressed in radians

ANG_DEG	The value of the angle is expressed in degrees (this is the default and does not need to be indicated)

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

All positive and negative numbers except infinity are acceptable for this function.

 Example:

invoke FpuSin, ADDR Src, 0, SRC1_REAL or ANG_RAD or DEST_FPU

In this example, the sine of the 80-bit REAL number at the TBYTE memory variable labeled Scr and expressed in radians is computed and is returned on the FPU if the function succeeds, the 2nd parameter being ignored.


FpuCos

The FpuCos function returns the cosine of an angle expressed in degrees or radians.

cos(x) Y Dest

 FpuCos (

lpSrc	//pointer to, or value of, angle (x)

lpDest	//pointer to destination of result

uID	//ID flags for source, angle type, and destination

)

 Parameters

lpSrc

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer, all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL cosine value will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with one of the ANG_? Flags and OR’ed with one of the DEST_? flags. (The ANG flag does not need to be OR’ed if the angle is in degrees; that is the default type. The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

SRC1_DMEM	Src is a pointer to a 32-bit signed integer

SRC1_DIMM	Src is a 32-bit signed integer

ANG_RAD	The value of the angle is expressed in radians

ANG_DEG	The value of the angle is expressed in degrees (this is the default and does not need to be indicated)

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

All positive and negative numbers except infinity are acceptable for this function.

 Example:

invoke FpuCos, 0, 0, SRC1_FPU or ANG_RAD or DEST_FPU

In this example, the cosine of the 80-bit REAL already on the FPU and expressed in radians is computed and is returned on the FPU replacing the source parameter if the function succeeds; both the 1st and 2nd parameters are ignored.


FpuTan

The FpuTan function returns the tangent of an angle expressed in degrees or radians.

tan(x) Y Dest

 FpuTan (

lpSrc	//pointer to, or value of, angle (x)

lpDest	//pointer to destination of result

uID	//ID flags for source, angle type, and destination

)

 Parameters

lpSrc

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer, all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL tangent value will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with one of the ANG_? Flags and OR’ed with one of the DEST_? flags. (The ANG flag does not need to be OR’ed if the angle is in degrees; that is the default type. The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

SRC1_DMEM	Src is a pointer to a 32-bit signed integer

SRC1_DIMM	Src is a 32-bit signed integer

ANG_RAD	The value of the angle is expressed in radians

ANG_DEG	The value of the angle is expressed in degrees (this is the default and does not need to be indicated)

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

All positive and negative numbers except infinity are acceptable for this function.

 Example:

invoke FpuTan, edx, ADDR Dest, SRC1_DIMM

In this example, the tangent of the 32-bit signed integer in EDX expressed in degrees is computed and transferred to the TBYTE memory variable labeled Dest if the function succeeds. All FPU registers would be preserved.


FpuArcsin

The FpuArcsin function returns the angle expressed in degrees or radians corresponding to the sine value provided as the source.

asin(x) Y Dest

 FpuArcsin (

lpSrc	//pointer to the sine value (x)

lpDest	//pointer to destination of result

uID	//ID flags for source, angle type, and destination

)

 Parameters

lpSrc

This parameter points to an 80-bit REAL number according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL angle value will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

One of the SRC1_? flags must be OR'ed with one of the ANG_? Flags and OR’ed with one of the DEST_? flags. (The ANG flag does not need to be OR’ed if the angle is required in degrees; that is the default type. The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

ANG_RAD	The value of the angle will be returned in radians

ANG_DEG	The value of the angle will be returned in degrees (this is the default and does not need to be indicated)

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

The source parameter must have a value within the range of -1 to +1 inclusive. Otherwise, the function will fail and return with the error code.

Negative values of a sine yield negative values of the corresponding angle. If the angle is specified to be in radians, it remains as is with a value between -½B and +½B inclusive. If the angle is specified to be in degrees, the negative values are modified to the 270-360 degree range; positive values remain in the 0-90 degree range.

If the angle with the corresponding sine is known to be in the other two quadrants (i.e. in the 90-270 degree range), its value must be subtracted from 180 to get the required result; this may lead to a negative angle which would require the addition of 360 to get it in the 0-360 positive range.

Similarly, if the angle in radians needs to be adjusted for the other two quadrants, its value must be subtracted from B to get the required result

 Example:

invoke FpuArcsin, 0, ADDR Dest, SRC1_FPU

In this example, the 1st parameter is ignored since the sine value is identified as being already on the FPU. The resulting angle in degrees will be stored at the TBYTE memory variable labeled Dest and the source parameter would be removed from the FPU if the function succeeds.


FpuArccos

The FpuArccos function returns the angle expressed in degrees or radians corresponding to the cosine value provided as the source.

acos(x) Y Dest

 FpuArccos (

lpSrc	//pointer to the cosine value (x)

lpDest	//pointer to destination of result

uID	//ID flags for source, angle type, and destination

)

 Parameters

lpSrc

This parameter points to an 80-bit REAL number according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL angle value will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

One of the SRC1_? flags must be OR'ed with one of the ANG_? Flags and OR’ed with one of the DEST_? flags. (The ANG flag does not need to be OR’ed if the angle is required in degrees; that is the default type. The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

ANG_RAD	The value of the angle will be returned in radians

ANG_DEG	The value of the angle will be returned in degrees (this is the default and does not need to be indicated)

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

The source parameter must have a value within the range of -1 to +1 inclusive. Otherwise, the function will fail and return with the error code.

Positive values of the cosine will result in angles within the range of 0 - ½B radians (0-90 degrees). Negative values of the cosine will result in angles within the range of ½B - B radians (90-180 degrees).

If the angle with the corresponding cosine is known to be in the other two quadrants (i.e. in the 180-360 degree range), its value must be subtracted from 360 to get the required result.

Similarly, if the angle in radians needs to be adjusted for the other two quadrants, its value must be subtracted from 2B to get the required result

 Example:

invoke FpuArccos, ADDR Src, ADDR Dest, SRC1_REAL or ANG_RAD

In this example, the cosine value is identified as being the 80-bit REAL at the TBYTE memory variable labeled Src. The resulting angle in radians will be stored at the TBYTE memory variable labeled Dest if the function succeeds. All FPU registers would be preserved.


FpuArctan

The FpuArctan function returns the angle expressed in degrees or radians corresponding to the tangent value provided as the source.

atan(x) Y Dest

 FpuArctan (

lpSrc	//pointer to the tangent value (x)

lpDest	//pointer to destination of result

uID	//ID flags for source, angle type, and destination

)

 Parameters

lpSrc

This parameter points to an 80-bit REAL number according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL angle value will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

One of the SRC1_? flags must be OR'ed with one of the ANG_? Flags and OR’ed with one of the DEST_? flags. (The ANG flag does not need to be OR’ed if the angle is required in degrees; that is the default type. The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

ANG_RAD	The value of the angle will be returned in radians

ANG_DEG	The value of the angle will be returned in degrees (this is the default and does not need to be indicated)

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it is transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

All positive and negative numbers (including the +/- infinity values) are acceptable as a source parameter for this function.

Negative values of a tangent yield negative values of the corresponding angle. If the angle is specified to be in radians, it remains as is with a value between -½B and +½B inclusive. If the angle is specified to be in degrees, the negative values are modified to the 270-360 degree range; positive values remain in the 0-90 degree range.

If the angle with the corresponding tangent is known to be in the other two quadrants (i.e. in the 90-270 degree range), a value of 180 will need to be added to the result.

Similarly, if the angle in radians needs to be adjusted for the other two quadrants, the value of B must be added to it.

 Example:

In the following example, the value of the angle formed by two vectors at right angle is computed. The value of the vector opposite the angle is available as an 80-bit REAL at the TBYTE variable labeled Opp and the value of the vector adjacent to the angle is also available as an 80-bit REAL at the TBYTE variable labeled Adj. The resulting angle in degrees will be stored as an 80-bit REAL at the TBYTE variable labeled Dest if the function succeeds.

Invoke FpuDiv, ADDR Opp, ADDR Adj, 0, SRC1_REAL or SRC2_REAL or DEST_FPU

invoke FpuArctan, 0, ADDR Dest, SRC1_FPU

The first function computes the tangent, leaving the result on the FPU (the FPU’s ST7 data register must be free). The second function computes the corresponding angle and stores the result expressed in degrees.


FpuSinh

The FpuSinh function returns the hyperbolic sine of a number.

sinh(x) Y Dest

 FpuSinh (

lpSrc	//pointer to, or value of, source number (x)

lpDest	//pointer to destination of result

uID	//ID flags for source, and destination

)

 Parameters

lpSrc

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer, all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL hyperbolic sine value will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

SRC1_DMEM	Src is a pointer to a 32-bit signed integer

SRC1_DIMM	Src is a 32-bit signed integer

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

All positive and negative numbers are acceptable for this function. However, very large absolute values of that number may exceed the limits of the FPU and return a value of infinity. This would not be considered as an invalid operation and would not return the error code, but the returned result may not be usable with other library functions.

 Example:

invoke FpuSinh, 0, ADDR Dest, SRC1_FPU

In this example, the 1st parameter is ignored and the hyperbolic sine of the 80-bit REAL number already on the FPU will be returned as an 80-bit REAL number at the TBYTE memory variable labeled Dest. The source operand would be removed from the FPU if the function succeeds.


FpuCosh

The FpuCosh function returns the hyperbolic cosine of a number.

cosh(x) Y Dest

 FpuCosh (

lpSrc	//pointer to, or value of, source number (x)

lpDest	//pointer to destination of result

uID	//ID flags for source, and destination

)

 Parameters

lpSrc

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer, all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL hyperbolic cosine value will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

SRC1_DMEM	Src is a pointer to a 32-bit signed integer

SRC1_DIMM	Src is a 32-bit signed integer

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

All positive and negative numbers are acceptable for this function. However, very large absolute values of that number may exceed the limits of the FPU and return a value of infinity. This would not be considered as an invalid operation and would not return the error code, but the returned result may not be usable with other library functions.

 Example:

invoke FpuCosh, 0, 0, SRC1_FPU or DEST_FPU

In this example, the 1st and 2nd parameters are ignored and the hyperbolic cosine of the 80-bit REAL number already on the FPU will replace it if the function succeeds.


FpuTanh

The FpuTanh function returns the hyperbolic tangent of a number.

tanh(x) Y Dest

 FpuTanh (

lpSrc	//pointer to, or value of, source number (x)

lpDest	//pointer to destination of result

uID	//ID flags for source, and destination

)

 Parameters

lpSrc

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer, all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL hyperbolic tangent value will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

SRC1_DMEM	Src is a pointer to a 32-bit signed integer

SRC1_DIMM	Src is a 32-bit signed integer

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

The hyperbolic tangent rapidly approaches the values of 1 (or -1) with increasing numbers. A source value of +/-23 already saturates the first 19 decimal places of the result with 9's.

The hyperbolic tangent is computed from the division of two exponential numbers. If a source value larger than approx. +/-11300 is used, such exponential numbers would reach a value of “infinity” and their division would result in an invalid operation.

 Example:

invoke FpuTanh, ADDR Src, 0, SRC1_REAL or DEST_FPU

In this example, the hyperbolic tangent of the 80-bit REAL number from the TBYTE memory variable labeled Src will be returned on the FPU if the function succeeds. The 2nd parameter is thus ignored.


FpuArcsinh

The FpuArcsinh function returns the number corresponding to a hyperbolic sine value.

asinh(x) Y Dest

 FpuSinh (

lpSrc	//pointer to, or value of, source number (x)

lpDest	//pointer to destination of result

uID	//ID flags for source, and destination

)

 Parameters

lpSrc

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer, all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL hyperbolic arcsine value will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

SRC1_DMEM	Src is a pointer to a 32-bit signed integer

SRC1_DIMM	Src is a 32-bit signed integer

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

All valid positive and negative values (except infinity) are acceptable as the source parameter for this function.

 Example:

invoke FpuArcsinh, ADDR Src, ADDR Dest, SRC1_REAL

In this example, the hyperbolic arcsine of the 80-bit REAL number from the TBYTE memory variable labeled Src will be stored as an 80-bit REAL number at the TBYTE memory variable labeled Dest if the function succeeds. The FPU returns unmodified.


FpuArccosh

The FpuArccosh function returns the number corresponding to a hyperbolic cosine value.

acosh(x) Y Dest

 FpuArccosh (

lpSrc	//pointer to, or value of, source number (x)

lpDest	//pointer to destination of result

uID	//ID flags for source, and destination

)

 Parameters

lpSrc

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer, all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL hyperbolic arccosine value will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

SRC1_DMEM	Src is a pointer to a 32-bit signed integer

SRC1_DIMM	Src is a 32-bit signed integer

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

Hyperbolic cosine values can only be positive and greater than or equal to 1. Only such values (except infinity) are thus acceptable as the source parameter for this function. The result will also be always returned positive although negative numbers can generate the same hyperbolic cosine values. If the negative result may be required, simply change its sign.

 Example:

invoke FpuArccosh, 0, 0, SRC1_FPU or DEST_FPU

In this example, the value already on the FPU is replaced by its hyperbolic arccosine if the function succeeds. Both the 1st and 2nd parameters are ignored.


FpuArctanh

The FpuArctanh function returns the number corresponding to a hyperbolic tangent value.

atanh(x) Y Dest

 FpuArctanh (

lpSrc	//pointer to, or value of, source number (x)

lpDest	//pointer to destination of result

uID	//ID flags for source, and destination

)

 Parameters

lpSrc

This parameter points to an 80-bit REAL number according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a TBYTE where the 80-bit REAL hyperbolic arctangent value will be returned. The result can instead be returned on the FPU according to the content of uID. (This parameter is ignored if uID indicates that the result should be returned on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with one of the DEST_? flags. (The DEST flag does not need to be OR’ed if the destination is in memory; that is the default destination.)

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

DEST_FPU	The result is returned on the FPU

DEST_MEM	lpDest is a pointer to a TBYTE (this is the default and does not need to be indicated)

 Return Values:

If the result is considered a valid REAL number, it will be transferred to the specified destination and EAX will be non-zero.

If the function fails, EAX will be zero and the specified source and destination will not be modified.

When the source is from the FPU, it will be discarded if the function succeeds; it would be replaced by the result when it is specified to be returned on the FPU. If the source is not from the FPU but the result must be returned on the FPU, the FPU’s ST7 data register must be free; otherwise, the content of that register will be trashed in order to return the required result.

All other FPU registers and all the CPU registers (except EAX) are preserved.

 Remarks:

The source parameter for this function must be within the range of -1 to +1 exclusive.

 Example:

invoke FpuArctanh, ADDR Src, 0, SRC1_REAL or DEST_FPU

In this example, the hyperbolic arctangent of the 80-bit REAL number from the TBYTE memory variable labeled Src will be computed and returned on the FPU if the function succeeds. The 2nd parameter is ignored.


FpuSize

The FpuSize function returns the exponent of a number as would be expressed in scientific notation.

 FpuSize (

lpSrc	//pointer to, or value of, source parameter

lpDest	//pointer to destination of result

uID	//ID flags for source and destination

)

 Parameters

lpSrc

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer, all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpDest

This points to a 32-bit LONG integer memory variable where the exponent will be returned.

uID

Only one of the SRC1_? flags must be used.

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

SRC1_DMEM	Src is a pointer to a 32-bit signed integer

SRC1_DIMM	Src is a 32-bit signed integer

 Return Values:

If the source is considered a valid non-zero number, its size will be transferred to the specified destination and EAX will be non-zero.

If the source is equal to zero, a value of -0 (80000000h) will be returned to the specified destination and EAX will be non-zero.

Otherwise, EAX will be zero and the specified destination will not be modified.

All the FPU registers and all the CPU registers (except EAX) are preserved. (If the source was on the FPU, its value on the FPU is preserved.)

 Remarks:

The sign of the source number is disregarded with this function. Negative results (including the negative zero) indicate absolute values less than 1, while positive results indicate absolute values higher than 1.

 Example:

invoke FpuSize, 0, ADDR Dest, SRC1_FPU

In this example, the 1st parameter is ignored and the size of the 80-bit REAL already on the FPU is returned to the LONG integer memory variable labeled Dest, the source 80-bit REAL value being preserved on the FPU.


FpuComp

The FpuComp function compares the 1st parameter to the 2nd parameter.

 FpuComp (

lpSrc1	//pointer to, or value of, 1st parameter

lpSrc2	//pointer to, or value of, 2nd parameter

uID	//ID flags for sources

)

 Parameters

lpSrc1

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER (see FPU Constants for description),

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

lpSrc2

This either points to an 80-bit REAL number or to a DWORD integer, or is an immediate DWORD integer or one of the FPU constants:

FPU_PI or FPU_NAPIER,

all according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

uID

Only one of the SRC1_? flags must be OR'ed with only one of the SRC2_? flags.

uID Flag	Meaning

SRC1_FPU	Src1 is already on the FPU

SRC1_REAL	Src1 is a pointer to an 80-bit REAL number

SRC1_DMEM	Src1 is a pointer to a 32-bit signed integer

SRC1_DIMM	Src1 is a 32-bit signed integer

SRC1_CONST	Src1 is one of the special FPU constants

SRC2_FPU	Src2 is already on the FPU

SRC2_REAL	Src2 is a pointer to an 80-bit REAL number

SRC2_DMEM	Src2 is a pointer to a 32-bit signed integer

SRC2_DIMM	Src2 is a 32-bit signed integer

SRC2_CONST	Src2 is one of the special FPU constants

 Return Values:

If either of the source numbers is considered invalid by the FPU, or cannot be compared such as a value of infinity, EAX returns with zero.

Otherwise, the result of the comparison is returned as coded bits in EAX which can be tested with the following constants:

CMP_EQU	if bit is set 	Src1 = Src2

CMP_GREATER	if bit is set	Src1 > Src2

CMP_LOWER	if bit is set	Src1 < Src2

Note: The FPU performs a signed comparison; negative numbers are smaller than positive numbers.

All the FPU registers and all the CPU registers (except EAX) are preserved. (If one of the sources was on the FPU, its value would be preserved.)

 Example:

invoke FpuComp,0,10,SRC1_FPU or SRC2_DIMM

or	eax,eax

jz	error_handler

test	eax,CMP_EQU or CMP_GREATER

jz	lower_than_10

In this example, the value already on the FPU is compared to the immediate value of 10. Then EAX is first checked for a non-comparable parameter (only the value on the FPU could be at fault in this example) and the code branching off to the error handler if necessary. Finally, EAX is tested for equal-or-greater and the jump made if the value on the FPU is lower than 10. The value on the FPU would be preserved.


FpuExam

The FpuExam function examines an 80-bit REAL number for its validity, its sign, a value of zero, an absolute value less than 1, and a value of infinity.

 FpuExam (

lpSrc	//pointer to source parameter

uID	//ID flag for source

)

 Parameters

lpSrc

This parameter points to an 80-bit REAL number according to the content of uID. (This parameter is ignored if uID indicates that the value is already on the FPU.)

uID

Only one of the SRC1_? flags must be used.

uID Flag	Meaning

SRC1_FPU	Src is already on the FPU

SRC1_REAL	Src is a pointer to an 80-bit REAL number

 Return Values:

The result of the examination is returned as coded bits in EAX which can be tested with the following constants:

XAM_VALID	if bit is set 	Src = valid 80-bit REAL

XAM_ZERO	if bit is set 	Src = zero

XAM_NEG	if bit is set 	Src = negative

XAM_SMALL	if bit is set 	Src = absolute value less than 1

XAM_INFINIT	if bit is set 	Src = infinity

All the FPU registers and all the CPU registers (except EAX) are preserved. (If the source was on the FPU, its value would be preserved.)

 Example:

invoke FpuExam, 0, SRC1_FPU

In this example, the 1st parameter is ignored and the 80-bit REAL number already on the FPU is examined, the result being returned in EAX. The value on the FPU would be preserved.


FpuState

The FpuState function returns a null-terminated string listing the content of the FPU registers to a memory buffer.

 FpuState (

lpszDest

)

lpszDest

This points to a memory location where the string will be returned. It must be large enough to hold the number of characters returned. A buffer size of 400 bytes would be sufficient.

 Return Values:

All the FPU registers and all the CPU registers are preserved.

The returned string is formatted as shown below when displayed in a Message Box:

Fields in the Control Word (RC and PC) and the Status Word (TOP) which would contain more than 1 bit have those bits grouped together.

The exception flags in the Status Word have an upper case letter if set or a lower case letter if clear.

The individual tags of the Tag Word are positioned to reflect the order of the data registers based on ST0.

The IP is the address of the last FPU instruction before using this function. The OA is the address of the memory operand if one was used by that last FPU instruction.

 Example:

invoke FpuState, ADDR Dest

In this example, the formatted string would be returned in the buffer labeled Dest.


FPU Constants

Two widely used constants are made available with the FPU, the value of pi (B = 3.14159...) and the value of the Napierian constant (e = 2.71828...). They can be used where permitted as the source for a number by specifying one of the following constants instead of a pointer to a REAL10 or an integer, and identifying it as such.

Constant	Meaning

FPU_PI	The value of B. This constant needs to be used in numerous computations such as those related to the circle or sphere.

For information, that constant is loaded on the FPU with the following instruction:

fldpi

FPU_NAPIER	The value of e. Although this constant is not directly available from the FPU as the one above, it is generated internally with a few FPU instructions when specified as a parameter.

For information, that constant is loaded on the FPU with the following instructions:

      fld1

      fldl2e

      fsub  st,st(1)

      f2xm1

      fadd  st,st(1)

      fscale

      fstp  st(1)


Example

This example makes use of some of the library functions to compute the monthly payments on a loan (such as a mortgage) according to the following equation:

where:

P =	principal (mortgage)

R =	interest rate for each period (expressed as a decimal)

N =	number of periods (generally number of months for a mortgage)

PMT=	payment for each period (generally monthly payments for a mortgage)

This example assumes that some input from a user has already been obtained as alphanumeric strings for the loan principal, the annual interest rate (%) and the term of the loan (years). That input is then converted to REAL10 values and corrected to the units required for the computation. The result is then computed and converted to its decimal representation with two decimal places ready for display.

The code also presumes that the interest on the loan can be compounded on a monthly basis. This simplifies the process by being able to simply divide the annual interest rate by 12. (Several more operations would have been required if the interest could only have been compounded on a semi-annual or annual basis.)

The entire source code of a fully functional demo is provided for assembly with MASM32 (the Fpu.lib and Fpu.inc files must be in the required sub-folders). Simply copy and paste it into your editor, modify the MASM32 path if necessary, save it and compile it. Or you may like to design your own “dialog box” to get user input and use the code as a procedure to prepare the results.

No error checking is included in this demo. It would be wise to add some if you use it as a procedure.

.486

.model flat, stdcall

option casemap :none   ; case sensitive

; #########################################################################

include \masm32\include\windows.inc

include \masm32\include\user32.inc

include \masm32\include\kernel32.inc

include \masm32\include\Fpu.inc

includelib \masm32\lib\user32.lib

includelib \masm32\lib\kernel32.lib

includelib \masm32\lib\Fpu.lib

; #########################################################################

.data

mortgage	dt	0

monthly_rate	dt	0

months	dt	0

temp_real	dt	0

loan_inp	db	"92500",0

rate_inp	db	"6.75",0

year_inp	db	"20",0

result	db	32 dup(0)

.code

start:

;convert loan principal input to REAL10 and store it

invoke FpuAtoFL, ADDR loan_inp, ADDR mortgage, DEST_MEM

;convert yearly interest (%) rate input to REAL10 and store it as a monthly fractional rate

invoke FpuAtoFL,ADDR rate_inp, 0, DEST_FPU

invoke FpuDiv, 0, 1200, ADDR monthly_rate, SRC1_FPU or SRC2_DIMM

;convert term of loan (years) input to REAL10 and store it as months

invoke FpuAtoFL, ADDR year_inp, 0, DEST_FPU

invoke FpuMul, 0, 12, ADDR months, SRC1_FPU or SRC2_DIMM

;compute the (1+R) portion, keeping it on the FPU, and then the (1+R)^n term

;and storing it as a temporary REAL10 value

invoke FpuAdd, ADDR monthly_rate, 1, 0, SRC1_REAL or SRC2_DIMM or DEST_FPU

invoke FpuXexpY, 0, ADDR months, ADDR temp_real, SRC1_FPU or SRC2_REAL

;compute the denominator of the equation and leave it on the FPU

invoke FpuSub, ADDR temp_real, 1, 0, SRC1_REAL or SRC2_DIMM or DEST_FPU

;divide the (1+R)^n term by that denominator and leave on the FPU

invoke FpuDiv, ADDR temp_real, 0, 0, SRC1_REAL or SRC2_FPU or DEST_FPU

;multiply by the other terms and leave answer on the FPU

invoke FpuMul, 0, ADDR monthly_rate, 0, SRC1_FPU or SRC2_REAL or DEST_FPU

invoke FpuMul, 0, ADDR mortgage, 0, SRC1_FPU or SRC2_REAL or DEST_FPU

;convert result to alphanumeric with 2 decimals and display

invoke FpuFLtoA, 0, 2, ADDR result, SRC1_FPU or SRC2_DIMM

invoke MessageBox, 0, ADDR result, 0, MB_OK

invoke ExitProcess, 0

; #########################################################################

end start


Legal

This library of functions may be used free of charge for personal non-commercial use. The library functions may not be used for any commercial program (including shareware) without the express permission from the author.

The author retains all copyright to the library and the source code of the modules.

The author may be reached at:	rayfil@hotmail.com


Acknowledgement

This library would never have been possible without the timely help and encouragement from Steve Hutchesson (hutch) during my early attempts with Win32 programming. My initial impression of it was like trying to learn a dozen alien dialects with instructions written in hieroglyphs. I was therefore enthusiastic when Steve invited me to prepare this library of functions for the FPU.

Thank you Steve.

Raymond Filiatreault