/*
 *  vector.h
 *
 *  Scott Wilson
 *  rswilson@ccrma.stanford.edu
 *  last updated:  June 15, 2003
 *  
 *	Defines some useful functions for allocating, freeing and operating
 *  on signal vectors (arrays of codec_float_t).
 *
 *  Follows the calling convention of input arguments before output
 *  arguments in the command line and output arguments passed by
 *  pointer reference.
 *
 *  For example the following code could be used to allocate a 256 sample vector.
 *
 *  codec_err_t err;
 *  vector_p 	myVector;
 *	
 *	err = vector_alloc(256, &myVector);
 *  if (err != NO_ERR)
 *		// .... deal with the error
 *
 *   Note that we passed a pointer to myVector even though it's already a pointer.
 *	 This is done so that vector_alloc can make the pointer we declared and make it
 *	 point to memory it allocates internally.  It also obeys the convention of
 *	 passing the argument by reference to remember that it will be changed inside
 *	 vector_alloc.
 *
 *	 Don't forget to free the memory again using vector_dealloc!
 *
 * 	 vector_clear needs the length of the vector as an argument because this vector 
 *	 definition is very simple and doesn't keep track of it.  It would be possible to
 *	 write a smarter one that remembered, but the convenience of having the option to
 *	 pass any codec_vector_p to a function expecting an array of floats is a good
 *	 reason to keep it simple.
 *
 *	 The vector_set group of functions simply allocate arrays of vectors.  These are
 *	 useful since we often deal with multi-channel audio files.  The audiofile_read and
 *   audiofile_write functions (see audiofile.h) expect to be passed codec_vector_set_p
 *	 types for writing audio samples read in and reading audio samples to be written out.
 */

#ifndef _VECTOR_H
#define _VECTOR_H

#include <stdint.h>
#include "codec.h"

// for internal use only
typedef	codec_float_t  _codec_vector_t;

// codec_vector_p - pointer to vector data type 
typedef	_codec_vector_t *codec_vector_p;
// codec_vector_set_p - pointer to set of vectors data type
typedef codec_vector_p *codec_vector_set_p;

// for a single vector ...
codec_err_t vector_alloc(uint32_t size, codec_vector_p *vector);
codec_err_t vector_clear(codec_vector_p vector, uint32_t size);
codec_err_t vector_dealloc(codec_vector_p vector);

// for a vector set ....
codec_err_t vector_set_alloc(uint32_t size, uint8_t chans, codec_vector_set_p *vector);
codec_err_t vector_set_clear(codec_vector_set_p vector, uint32_t size, uint8_t chans);
codec_err_t vector_set_dealloc(codec_vector_set_p vector, uint8_t chans);

// useful vector operations
codec_float_t vector_sum(codec_vector_p signal, uint16_t blocksize);
codec_float_t vector_max(codec_vector_p signal, uint16_t blocksize);
codec_float_t vector_abs_max(codec_vector_p signal, uint16_t blocksize);

/* note: the following functions change the original vector */

codec_err_t vector_scale(codec_vector_p signal, uint16_t blocksize, codec_float_t scale_factor);
codec_err_t vector_square(codec_vector_p signal, uint16_t blocksize);
 // result stored in v1
codec_err_t vector_subtract(codec_vector_p v1,codec_vector_p v2, uint16_t blocksize);

#endif