GEOS SDK TechDocs
|
| 
4.1 Floating Point Numbers
| 
4.3 Floating Point Math Routines
Floating Point (FP) numbers are placed and manipulated on an FP stack. Numbers can be rearranged, operated on, and removed from this stack through pushes, pops, and the use of special routines.
FloatInit(), FloatExit()
Before performing any floating point operations, a thread needs to call
FloatInit()
to create and initialize an FP stack. Each thread using floats must have its own unique FP stack. This call to
FloatInit()
is automatically performed by any application that includes the Math Library.
FloatInit()
creates a swapable block of memory for the thread, initializes various stack pointers, and stores the handle for the block in the thread's data structure.
FloatInit()
must be passed the size of the stack to create (in bytes) and the type of stack (
FloatStackType
) to create.
The default FP stack holds 25 FP elements (250 bytes). An FP stack must be able to hold at least 5 FP elements.
The default floating point stack is FLOAT_STACK_GROW which instructs the system to increase the size of the stack whenever its bounds are reached. This is done automatically.
Other
FloatStackType
types are FLOAT_STACK_WRAP, which drops the FP numbers at the low end of the stack (effectively wrapping over that end) and FLOAT_STACK_ERROR which signals an error when the stack limit has been reached.
FloatExit()
detaches the floating point stack for the current thread and frees its memory.
FloatExit()
only frees the FP stack associated with the current thread; other FP stacks in other threads remain unaffected. As is the case with
FloatInit()
, the call to
FloatExit()
is automatically performed by any application that includes the Math Library.
If
FloatInit()
is called twice before calling
FloatExit()
, the data on the original floating point stack will be lost.
FloatPushNumber(), FloatPopNumber(), FloatDepth()
FloatPushNumber()
pushes an FP number onto the top of the FP stack for the current thread from a passed buffer. The number must be already set up in 80 bit, FP format. The routine must be passed the pointer to the buffer storing the number.
Similarly,
FloatPopNumber()
pops an FP number from the top of the FP stack for the current thread into a passed buffer.
FloatDepth()
returns the number of FP numbers currently in place on the stack.
Note: For clarity in diagrams within this chapter, stack locations will be numbered in order from the top position of the stack, S1 being first, S2 being second, etc. Variables will be numbered in the order they are pushed onto the stack, so that if X1, X2, and X3 are pushed onto the stack, the format illustrated below will result.
FloatRoll(), FloatRollDown(), FloatRot(), FloatSwap()
Besides basic pushing and popping, the Float Library also includes many other routines which manage FP numbers on the stack. Unless otherwise specified, an operation that pushes, pops, or extracts an FP number on the stack affects all other FP numbers below the position of the operation by shifting their location in the stack either up or down, in standard stack fashion.
FloatRoll()
pushes a selected FP number (S
X
) onto the top of the stack (S1), removing it from location SX in the process.
FloatRoll()
passed with a value of 3 would move the FP number in S3 onto the top of the stack, pushing the stack in the process. All FP numbers below the extracted number remain unaffected by this routine.
FloatRollDown()
performs the inverse operation of
FloatRoll()
. popping the top stack value (S1) into the specified location on the stack (S
X
).
FloatRollDown()
passed with a value of 3 would move the FP number in S1 into location S3, shifting the stack in the process.
Both of these routines must be passed a stack location to move to or from.
FloatRot()
rotates the top three numbers on the stack, placing S3 onto the top of the stack. This is equivalent to a
FloatRoll()
passed with a value of 3.
FloatSwap()
exchanges S1 and S2.
Repetitious applications of these routines will return the stack to its former state.
FloatPick(), FloatOver(), FloatDrop(), FloatDup()
FloatPick()
copies the contents of S
X
and pushes that value onto the FP stack. The entire stack is pushed in the process.
FloatPick()
passed with a value of 3 would copy the contents of S3 onto the FP stack.
FloatOver()
copies S2 to the top of the stack, equivalent to a
FloatPick()
passed with a value of 2.
FloatDrop()
drops (pops) the top number (S1) off the FP stack. This routine is different than
FloatPopNumber()
because the routine does not place the popped number into a memory address, and is therefore much faster.
FloatDup()
duplicates the value at S1, pushing it onto the top of the stack. The stack is pushed in the process.
FloatComp(), FloatCompESDI(), FloatCompAndDrop()
These routines essentially perform the same operation as the Assembly command
cmp
.
FloatComp()
performs a compare of the top two FP numbers (S1 and S2) and sets the appropriate flags in the flags register. The two FP numbers remain on the stack.
FloatCompESDI()
compares the contents of
es:[di]
with the value in S1 (and the FP number in S1 remains on the stack).
FloatCompAndDrop()
performs a compare of S1 and S2 and drops both from the FP stack.
FloatGetStackPointer(), FloatSetStackPointer()
FloatGetStackPointer()
returns the current stack pointer value of the FP stack.
FloatSetStackPointer()
sets the stack pointer to a previous position. This routine must be passed a value that is greater than or equal to the current value of the stack pointer. (I.e. you must be throwing something, or nothing, away.)
These routines may be useful before the execution of involved routines that may push many numbers onto the stack. If an unrecoverable error is encountered, the programmer need not pop the intermediate values off the stack to return to the previous stack configuration. Only the stack pointer is saved; the state of the stack is not. If any numbers below the stack pointer are popped or altered,
FloatSetStackPointer()
will not recover the previous state of the stack.
GEOS SDK TechDocs
|
| 4.1 Floating Point Numbers
| 4.3 Floating Point Math Routines