          The packed binary library
%BCROSS
  
 CALL BCROSS(A1,B1,A2,B2,I1,I2,IZ,FAIL,ISIZE)

 Purpose:  to find how line A1,B1 crosses line A2,B2 projected
           projected onto the xy plane
          
 Parameters:

       Input in fixed point binary 3-vectors:
   A1,B1 - coordinates of the ends of first line
   A2,B2 - coordinates of the ends of second line

       Results:
   I1    - INTEGER
           -1 : crossing is before first point of line 1
            0 : crossing is between points of line 1    
           +1 : crossing is after second point of line 1
   I2    - INTEGER as I1 but for line 2
   IZ    - INTEGER
            -1,0,+1 : crossing point on line 1 is behind,
                      same or in front of point on line 2
   FAIL  - LOGICAL
             .TRUE. if lines are parallel
             .FALSE. OK

   ISIZE - input INTEGER : suitable right shift for 
           the coordinates so that products of their
           separations do not exceed 32 bits
         
%BOVER

 LOGICAL FUNCTION BOVER (XYZ,XYP,N,ISIZE)

 Purpose: to determine whether a point lies inside a polygon

 Parameters:

      Input in fixed point:
  XYZ(N) - 3-vectors of a polygon
  XYP    - the point in xy plane
  ISIZE  - input INTEGER : suitable right shift for 
           the coordinates so that products of their
           distances from XYP do not exceed 32 bits
      Result:
  BOVER  - LOGICAL .TRUE. if XYP is within XYZ
                   .FALSE. otherwise

%BPTM2D
 
 CALL BPTM2D(BM,R8,M,N)

 Purpose: to convert binary.M to REAL*8

 Parameters:

   BM   - input array of binary.M 32-bit words
   R8   - output array of REAL*8 words
   M    - input binary point position
   N    - length of array

 Note: BM and R8 must not overlap in memory


%BPTM2R
 
 CALL BPTM2R(BM,R4,M,N)

 Purpose: to convert binary.M to REAL*4

 Parameters:

   BM   - input array of binary.M 32-bit words
   R4   - output array of REAL*4 words
   M    - input binary point position
   N    - length of array

 Note: BM and R4 may be equivalenced exactly

%BVCROS

 CALL BVCROS(A,B,C)

 Purpose: to calculate a cross product (C) of
          direction cosines (A & B)

 Parameters:

  A,B - Input direction cosines in format binary.30
  C   - Resultant direction cosine (binary.30)

%BVDIST

 INTEGER FUNCTION BVDIST(X1,X2,N)

 Purpose: to find the distance between vectors

 Parameters:

  X1,X2 - input fixed point N-vectors
  N     - input INTEGER: size of the vectors

 Result: has the same binary point as the input

 Note:   overflows will give the wrong answer

%BVDST2

 INTEGER FUNCTION BVDST2(X1,X2,N)

 Purpose: to find the squared distance between vectors

 Parameters:

  X1,X2 - input fixed point N-vectors
  N     - input INTEGER: size of the vectors

 Result: has the sum of the binary points of the input

 Note:   overflows will give the wrong answer

%BVMOD

 INTEGER FUNCTION BVMOD(X,N)

 Purpose: Finds the length of a N-vector

 Parameters:

  X  - a fixed point vector
  N  - the size of the vector

 Result: has the same binary point as the input

 Note:   overflows will give the wrong answer

%BVMOD2

 INTEGER FUNCTION BVMOD2(X,N)

 Purpose: Finds the squared length of a N-vector

 Parameters:

  X  - a fixed point vector
  N  - the size of the vector

 Result: has twice the binary point as the input

 Note:   overflows will give the wrong answer

%BVUNIT

 CALL BVUNIT(A,X,N)

 Purpose: sets  X = A/|A|

 Parameters:

   A - Input fixed point N-vector
   X - Output binary.30 N-vector
   N - size of vectors

 Note: the binary point of the input is irrelevant

%D2BPTM

 CALL D2BPTM (R8,BM,M,N)

 Purpose:  convert N REAL*8 to binary.M (32-bits)

 Parameters:

  R8  - Input REAL*8 array
  BM  - OUTPUT binary.M array
  M   - Input biary point position required
  N   - how many numbers to convert

 Note: R8 and BM may be the same array
       Overflows are ignored and will give the wrong answer

%DOTVB

 REAL FUNCTION DOTVB(IV1,IV2)

 Purpose: to find the dot product of direction cosines
          IV1 and IV2

 Parameters:
 
  IV1,IV2 - Input 3-vectors of binary.30 direction cosines

  Result: REAL result in the range -1.0 to 1.0
          can be REAL*4 or REAL*8

%IBCOMA

 INTEGER FUNCTION IBCOMA(A,B,M,N)

 Purpose:  returns I if A=+-B(I) for I=1,N; A and B are M-vectors

 Parameters:

  A - M-vector of elements to search for
  B - array of N such vectors to search through
  M - dimension of a vector
  N - number of vectors in B

  Result: index of match, or 0 if none.

%IBCOMS

 INTEGER FUNCTION IBCOMS(A,B,M,N)

 Purpose:  returns I if A=B(I) for I=1,N; A and B are M-vectors

 Parameters:

  A - M-vector of elements to search for
  B - array of N such vectors to search through
  M - dimension of a vector
  N - number of vectors in B

  Result: index of match, or 0 if none.

%KOLPK

 CALL KOLPK(IR,IG,IB,KOL)

 Purpose: to pack three colours into a colour word

 Parameters:

   IR  - INTEGER or BYTE, amount (0-255) of red to pack
   IG  - INTEGER or BYTE, amount (0-255) of green to pack
   IB  - INTEGER or BYTE, amount (0-255) of blue to pack
   KOL - Integer*4 resulting packed word (BBGGRR00)

 Note: the lowest order byte in the result is set to zero


%KOLPK1

 CALL KOLPK(IR,IG,IB,KOL)

 Purpose: to pack three colours into a colour word preserving
          the lowest order byte

 Parameters:

   IR  - INTEGER or BYTE, amount (0-255) of red to pack
   IG  - INTEGER or BYTE, amount (0-255) of green to pack
   IB  - INTEGER or BYTE, amount (0-255) of blue to pack
   KOL - Integer*4 resulting packed word (BBGGRRxx)

 Note: the lowest order byte in the result is preserved

%KOLUNP

 CALL KOLUNP(KOL,IR,IG,IB)

 Purpose: to unp pack three colours from a colour word

 Parameters:

   KOL - Integer*4 resulting packed word (BBGGRRxx)
   IR  - INTEGER, amount (0-255) of red in KOL
   IG  - INTEGER, amount (0-255) of green in KOL
   IB  - INTEGER, amount (0-255) of blue to KOL

 Notes: 1 the lowest order byte in KOL is ignored
        2 the results are 4-byte integers with the top 24 bits zeroed

%PSPECB

 CALL PSPECB(X,IPSFAC,X1,M)

 Purpose: To transform from stored (X,Y,Z) to screen (X1,Y1)

 Parameters:

  X      -  3-vector coordinates of point to plot
  IPSFAC -  is the reciprocal of the eye distance
            in units of (X,Y,Z). If IPSFAC = 0 there is no perspective
  X1     -  resulting 2-vector t5o plot
  M      -  scaling factor: see below

 Notes: X1(Y1)=X(Y)/(1-Z*IPSFAC) / 2**M
      IPSFAC must in binary.(48-K) when Z is in binary.K
      |Z|*IPSFAC should be much less than 1.0 and IPSFAC must be >=0
      E.g. with Z in binary.28, IPSFAC (in binary.20) must be
      much less than 1/maximum value of |Z|, where 20 = 48 - 28
      Choose a good value for M such the result (X1,Y1) is of
      suitable integer size for direct plotting on the screen.

%R2BPTM


 CALL R2BPTM (R4,BM,M,N)

 Purpose:  convert N REAL*4 to binary.M (32-bits)

 Parameters:

  R4  - Input REAL*4 array
  BM  - OUTPUT binary.M array
  M   - Input biary point position required
  N   - INTEGER how many numbers to convert

 Note: R4 and BM may be the same array
       Overflows are ignored and will give the wrong answer

%ROTATB

 CALL ROTATB(X,Y,THETA,N)

 Purpose: rotates (X,Y) by REAL*4 THETA (degrees)

Parameters:

  X,Y   - (x,y) coordinates of 2-D vector to rotate
          (arbitrary fixed point) assumed to be part of
          an array of 3-vectors, e.g. DIMENSION XYZ(3,M)
  THETA - REAL*4 angle to rotate in degrees
  N     - number of pairs to rotate

Notes:
      X'=X*COS(THETA)-Y*SIN(THETA)
      Y'=Y*COS(THETA)+X*SIN(THETA)
      overwrite the original X,Y in the same fixed point

%ROTVB

 CALL ROTVB(XYZ,AXIS,THETA,N)

 Purpoose: To rotate N vectors of XYZ by REAL*4 THETA (degrees)
           about an axis

 Parameters:

  XYZ   - fixed-point array of N 3-vectors to rotate
  AXIS  - direction cosines of axis for rotation (binary.30)
  THETA - REAL*4 angle to rotate (degrees)
  N     - INTEGER numberof vectors in XYZ to transform

Notes:

   XYZ is overwritten with the result
   fixed point position is arbitrary but conserved


%SCALEB

 CALL SCALEB(X,SCALE,X1,N)

 Purpose: to scale a vector

 Parameters

  X     - Fixed point array
  SCALE - REAL*4 scale factor
  X1    - Resulting array of fixed-point
  N     - Length of array

Notes:

    The point position is arbitrary and preserved
    IF SCALE is to big, routine does nothing!

%VISIBL

 LOGICAL FUNCTION VISIBL(XYZ,DC,IPSFAC)

 Purpose: To determine if a polyhedron face is visible to the screen

 Parameters:

  XYZ    - Fixed-point: a vertex of the polygon (3D)
  DC     - Binary.30 array of direction cosines of normal to face
  IPSFAC - is the reciprocal of the eye distance
           in units of (X,Y,Z). If IPSFAC = 0 there is no perspective

 Notes:
      IPSFAC must in binary.(48-K) when XYZ is in binary.K
      |Z|*IPSFAC should be much less than 1.0 and IPSFAC must be >=0
      E.g. with Z in binary.28, IPSFAC (in binary.20) must be
      much less than 1/maximum value of |Z|, where 20 = 48 - 28

