/*
 * Copyright 1994 James D. Yegerlehner 
 * All Rights Reserved  
 * Alle Rechte Vorbehalten
 *
 * This file contains the prototypes of the functions contained in
 * the archive DSPMATH.LIB, version 1.0.  
 *
 * Use this library at your own risk. It appears to work, but I've
 * done very little testing. 
 * 
 * You are welcome to use this library in developing software
 * so long as you do not sell the software. If you have a commercial
 * application, get ahold of me and I will be happy to license
 * it to you. It probably needs a little customization to be commercial
 * anyway.
 *  
 */


/*
 * This library won't coexist too well with other applications that use the DSP.
 * Grab_DSP() grabs the DSP and leaves it locked and unavailable
 * to other applications until a Release_DSP() call is made. 
 *
 * Grab_DSP() returns either DSP_OK if the DSP was successfully initialized (it expects
 * DSPMATH.LOD to be in the current directory).  DSP_BUSY is returned if some other
 * application is using the DSP, and UHOH if it couldn't find DSPMATH.LOD.
 * 
 *
 * 24. Januar 94
 *
 */
 
/*  Grab_DSP() return code */
#define DSP_OK		0
#define DSP_BUSY	1
#define UH_OH		2

int     Grab_DSP(void);
void    Release_DSP(void);


/*
 * Mat_Mult forms the product of two matrices A and B, and returns the result
 * in C. That is:
 * 
 *    C     = A      B
 *     m x r   m x n   n x r
 *
 * where m,n and r are the matrix dimensions.
 *
 * Aptr, Bptr, and Cptr are pointers to the arrays containing the elements
 * of matrices A, B, and C, respectively. The array pointed to by each pointer
 * should be of a size equal to the product of the dimensions the matrix. E.g.,
 * The array pointed at by Aptr should be of size m*n floats. The correspondance 
 * between array and matrix elements is given by:
 * (*Aptr)              ==  A row 1, column 1
 * (*Aptr + 1)          ==  A row 1, column 2
 *   :
 * (*Aptr + n - 1)      ==  A row 1, column n
 * (*Aptr + n )         ==  A row 2, column 1
 * (*Aptr + n + 1)      ==  A row 2, column 2
 *   :
 * (*Aptr + 2n -1)      ==  A row 2, column n
 *   :
 * (*Aptr + m*n -1)     ==  A row m, column n
 *   
 * The pointers Adptr, Bdptr, and Cdptr are pointers to arrays 
 * of unsigned longs, of the same sizes as Aptr, Bptr, and Cptr.
 * They are used as buffers by Mat_Mult to hold the fixed-point 
 * representations of A, B and C, and thus don't need to be 
 * initialized. Mat_Mult could have dynamically allocated them
 * itself, but memory allocation is funny on STs, so it's left
 * to the application.
 *
 */
void
matmlflt(float          *Aptr,
         float          *Bptr,
         float          *Cptr,
         unsigned long  m,
         unsigned long  n,
         unsigned long  r,
         unsigned long  *Adptr,
         unsigned long  *Bdptr,
         unsigned long  *Cdptr);


/*
 *
 * matmlfxp is identical to matmlflt except that pointers to arrays of 24-bit fixed point
 * numbers containing A B and C are passed. The matrix C is returned in the array pointed
 * to by Cdptr. This one is much faster than matmlflt because it doesn't have the overhead
 * of converting the floats to fixed point numbers and back again. 
 *
 * 
 */
void
matmlfxp(unsigned long  m,
         unsigned long  n,
         unsigned long  r,
         unsigned long  *Adptr,
         unsigned long  *Bdptr,
         unsigned long  *Cdptr);

/* DSP_to_f converts a 24-bit fixed point (fractional 2's complement) number
 * used by the DSP 56001 (packed in the least signifigant 24 bits of the long) to
 * a single precision floating point number in the IEEE format, like that supported
 * by Turbo C and Pure C. 
 */
float
DSP_to_f(unsigned long dspval);

/* f_to_DSP converts a single precision floating point number between -1.0 and 0.999999
 * to a 24 bit fixed point number used by the DSP 56001. 
 * The floating point number must have been scaled already to between 0.999999 and -1.0
 */
unsigned long
f_to_DSP(float fval);