
                     Bmath  v.03.01
                     ~~~~~~~~~~~~~~
                  (math with Bittians)
           copyright  2001 by dennis crombie

           OSI Certified Open Source Software

              (MASM32 assembly source code)
                     dc@bmath.net
=================================================================
this version:
	square root for zero is corected
=================================================================
To date, Bmath has the following features:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

>   bMath        Initialization PROC (Constants, tables...)

Conversion Constants:
~~~~~~~~~~~~~~~~~~~~~
>   R2B, B2R, D2B, B2D, R2D, D2R      (more on these below)

MACROs:
~~~~~~~
>   bSin, dSin, rSin:
        returns Sin of any size 'Bittian' Angle in !27! clocks.
                (!30! for dSin using degrees and
                 rSin using radians for inputs)

>   bCos, dCos, rCos:
        returns Cos of any size 'Bittian' Angle in !27! clocks.
                (!30! for dCos using degrees and
                 rCos using radians for inputs)

>   bSqrt:
        Square Roots in 23 clocks


>   bBTN, rBTN, dBTN:
        get BTN * in 12 clocks (9 for Bittian input) more then 3 times faster
             then a FDIV !!

*  !! BTN !!   the variable 'BTN' obtains sector, quadrant, octant...(BTN)
               position bitmapped down to the Bittian (roughly 1/3 degree)
               (BTN is also given as a side affect to bMath Reduce fn's)
                    bit 9 = sector
                    bits 8, 9 = quadrant
                    bits 7, 8, 9 = octant
                    .
                    .
                    .

               (xxxx xxxx xxxx xxxx xxxx xxSx xxxx xxxx)
               (xxxx xxxx xxxx xxxx xxxx xxQQ xxxx xxxx)
               (xxxx xxxx xxxx xxxx xxxx xxOO Oxxx xxxx)
                    .
                    .
                    .

>   bReduce, rReduce, dReduce:
        reduces angle faster then a FDIV

example:
        fadd        unknown ;  quantity to your angle
        rReduce                ;  to < 2pi

if TOS was = 1.5pi, unknown = 1.8pi, together = 3.3pi, reduction
 leaves 1.3pi in TOS

if TOS was = 300 deg, unknown = 5000 deg, together = 5300 deg,
 dReduce would give result: 260.0

=================================================================

   if you can use input angles that 'SNAP' (round to nearest)
        to Bittians (+/- roughly 1/6 degree), you can have sin
        or cos results in 17 clocks, 14 for Bittian input,
        or both in 18, 15 for btn's.
         
                'Snapping Angle' Fn's:

>   bSnapS, dSnapS, rSnapS
        sin for 'Snappy' AngleIn

>   bSnapC, dSnapC, rSnapC
        cos for 'Snappy' AngleIn

>   bSnapSC, dSnapSC, rSnapSC
        sin in TOS, cos in ST(1)

>   bSnapCS, dSnapCS, rSnapCS
        cos in TOS, sin in ST(1)

        These Fn's can use the 's' (not 'S') suffix to
         preserve ESI

        accuracy for snappy calcs can appear to be about 2.5
         digits, but the angle is changed slightly in the snap
         and the results for these snapped angles is actually
         next to perfect.

>   bSC, dSC, rSC:
        leaves Sin in TOS and Cos in ST(1) in !40! clocks.
                (!37! for Bittians)

   bCS, dCS, rCS:
        leaves Cos in TOS and Sin in ST(1) in !40! clocks.
                (!37! for Bittians)

==========================================================
                        How it Works:
                        ~~~~~~~~~~~~~
        1024 (1k) Bittians = 360 Degrees = 2pi Radians
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
           (Bmath is short for math using Bittians)

bFunctions convert the input angle to Bittians, putting the angle
 in a state that can take advantage of 2's compliment principals
 to extract a basic angle using simple logic.

Bittians is my answer to the problems involved with logical
 extraction of simple angles and the need for quick trig results.
 Using 1024 (1k) Bittians rather than 360 Degrees or 2(pi) Radians
 has many benifits:

          you can evenly divide 1024 by 2's all the way down to 1,
        
        the lower 10 bits of any sized ineger bAngle, whether
         positive or negative, is the simplified angle in Bittians!
                (00 0000 0000 b = 0 (=1024 : 1 00 0000 0000)
                 11 1111 1111 b = 1023 = -1)
         this gives the angle variable itself a clock-like property.

converting to Bittians from either Radians or Degrees is as easy as:
                fmul        R2B
 (one of the 6 conversion const's init'd by invoking bMath.)

conversion constants:
        D2B - Degrees to Bittians
        R2B - Radians to Bittians
        B2D - Bittians to Degrees
        B2R - Bittians to Radians
        D2R - Degrees to Radians
        R2D - Radians to Degrees

==========================================================
                To use:
                ~~~~~~~
  include the following lines in your code:

        include Bmath.asm        
        include Bmath.inc ;(or Bmathecx.inc to use ecx instead of esi)
        
        invoke Bmath
;Bmath is called with 0 parameters to init the tables and FPU. 


;                to use bFn's:
;                ~~~~~~~~~~~~~
        fld        AngleIn
        rSin                        ; get sin(AngleIn)
        
;                or

        fld        ADDR        lpAngleIn
        dCosS                        ; get cos(AngleIn), preserve ESI
        
;        result is left on TOS (top of stack in the FPU)
        
;        b, d, r prefix assigns input as Bittians, Degrees,
;        Radians, respectively. example:
        
         fld        ADDR        lpPoint1x    ;  input angle
         rCos                                ;  get cos for angle in radians
         fstp       ADDR        lpPoint1xx   ;  destination = cos out
         
==========================================================
                Preserving Registers
                ~~~~~~~~~~~~~~~~~~~~
   suffix 'S' (as in: 'rCosS') causes generation of epilog and
    prolog code to retain the value of ESI (+2 clocks)
                                       ~~~
   suffix 'D' (as in: 'bSinD') causes generation of epilog and
    prolog code to retain the value of EDI (+2 clocks)
                                       ~~~
   suffix 'B' (as in: 'dSCB') causes generation of epilog and
    prolog code to retain the value of BOTH EDI and ESI (+4 clks)
                                       ~~~~ ~~~     ~~~
Using Bmathecx.inc instead of Bmath.inc uses macros that use ecx
instead of esi and the suffixes 'S' and 'B' will preserve ecx.
==========================================================
            bFn code
            ~~~~~~~~
bMath functions are inline (MACROs), this way no jump and return
 code is processed, saving 5 or so percent on time.

==========================================================
1985) 8 bit version of Bittians (I now call them Bytians) concieved
        on a Commodore 64 while I was toying with 3d. pi/128 gave the 
        conversion factor, whereas:
        pi/512 = conversion factor for 10 bit (+fractional) Bittians.

