/**********************************************************************
audio play & record (Linux, Solaris, IRIX)

$Id: playrec.h,v 1.7 2003/01/19 23:17:09 purnhage Exp $

Header file: playrec.h

(c) Heiko Purnhagen 1998-2003
e-mail: purnhage@tnt.uni-hannover.de
WWW:    http://www.tnt.uni-hannover.de/~purnhage/

This module is available under the terms of the GNU Lesser General
Public License. See file COPYING-LGPL for further details. All usual
disclaimers apply!

Authors:
HP    Heiko Purnhagen, Uni Hannover <purnhage@tnt.uni-hannover.de>
NM    Nikolaus Meine, Uni Hannover (c/o Heiko Purnhagen)
BE    Bernd Edler, Uni Hannover <edler@tnt.uni-hannover.de>

Changes:
16-sep-98   HP/NM   born, based on auplay.c and aurec.c
            HP/BE   ... and play_list.c
08-jan-99   HP      audio device selection
19-nov-99   HP      added PRWriteBuffer(), PRWriteFilled(), PRNap()
04-Dec-2002 HP      PRReadData()/PRWriteData() now return error flag
01-Feb-2002 HP      added PROpenReadFrag(), PROpenWriteFrag()
**********************************************************************/

/* Audio play & record for Solaris, Linux, IRIX. */
/* Sample format: 16 bit twos complement, uniform quantisation */

/* Multi channel data is interleaved: l0 r0 l1 r1 ... */


#ifndef _playrec_h_
#define _playrec_h_


/* ---------- declarations ---------- */

typedef struct PRStreamStruct PRStream;	/* play/rec stream handle */


/* ---------- functions ---------- */

#ifdef __cplusplus
extern "C" {
#endif


/* PRInit() */
/* Init audio play & record. */

void PRInit (
  int debugLevel);		/* in: debug level */
				/*     -1=no warnings 0=off  1=basic  2=full */


/* PRNap() */
/* nap for ms milliseconds */

void PRNap (
  int ms);			/* in: time to nap [ms] */


/* PROpenRead() */
/* Open play/rec stream for reading. */

PRStream *PROpenRead (
  char *device,			/* in: device name (NULL = default device) */
  int *numChannel,		/* in/out: number of channels */
  float *fSample);		/* in/out: sampling frequency [Hz] */
				/*  numChannel & fSample: */
				/*  in: requested configuration */
				/*      (SGI: 0 = use audio panel settings) */
				/*  out: selected configuration */
				/*       (set according to audio */
				/*        device capabilities) */
				/* returns: */
				/*  play/rec stream (handle) */
				/*  or NULL if error */


/* PROpenWrite() */
/* Open play/rec stream for writing. */

PRStream *PROpenWrite (
  char *device,			/* in: device name (NULL = default device) */
  int *numChannel,		/* in/out: number of channels */
  float *fSample);		/* in/out: sampling frequency [Hz] */
				/*  numChannel & fSample: */
				/*  in: requested configuration */
				/*      (SGI: 0 = use audio panel settings) */
				/*  out: selected configuration */
				/*       (set according to audio */
				/*        device capabilities) */
				/* returns: */
				/*  play/rec stream (handle) */
				/*  or NULL if error */


/* PROpenReadFrag() */
/* Open play/rec stream for reading. */

PRStream *PROpenReadFrag (
  char *device,			/* in: device name (NULL = default device) */
  int *numChannel,		/* in/out: number of channels */
  float *fSample,		/* in/out: sampling frequency [Hz] */
  int *fragsize,		/* in/out: fragment size (samples) */
  int *fragstotal);		/* in/out: number of fragments */
				/*  numChannel & fSample: */
				/*  in: requested configuration */
				/*      (SGI: 0 = use audio panel settings) */
				/*  out: selected configuration */
				/*       (set according to audio */
				/*        device capabilities) */
				/*  frags: NULL or 0 = dflt/unkown */
				/* returns: */
				/*  play/rec stream (handle) */
				/*  or NULL if error */


/* PROpenWriteFrag() */
/* Open play/rec stream for writing. */

PRStream *PROpenWriteFrag (
  char *device,			/* in: device name (NULL = default device) */
  int *numChannel,		/* in/out: number of channels */
  float *fSample,		/* in/out: sampling frequency [Hz] */
  int *fragsize,		/* in/out: fragment size (samples) */
  int *fragstotal);		/* in/out: number of fragments */
				/*  numChannel & fSample: */
				/*  in: requested configuration */
				/*      (SGI: 0 = use audio panel settings) */
				/*  out: selected configuration */
				/*       (set according to audio */
				/*        device capabilities) */
				/*  frags: NULL or 0 = dflt/unkown */
				/* returns: */
				/*  play/rec stream (handle) */
				/*  or NULL if error */


/* PRReadData() */
/* Read data from play/rec stream. */

int PRReadData (
  PRStream *stream,		/* in: play/rec stream (handle) */
  short *data,			/* out: data[] */
  long numSample);		/* in: number of samples to be read */
				/* returns: */
				/*  0=OK 1=ERROR */


/* PRWriteBuffer() */
/* Set play buffer size. */
/* PRWriteData() waits until less than bufNumSample´s are left in play */
/* buffer before writing the new samples. */

void PRWriteBuffer (
  PRStream *stream,		/* in: play/rec stream (handle) */
  long bufNumSample);		/* in: number of samples in play buffer */
				/*     (0 to use max. available buffer) */


/* PRWriteFilled() */
/* Get number of samples currently left in play buffer, */
/* i.e. written by PRWriteData() but not yet played. */

long PRWriteFilled (
  PRStream *stream);		/* in: play/rec stream (handle) */
				/* returns: */
				/*  number of samples left in play buffer */


/* PRWriteData() */
/* Write data to play/rec stream. */

int PRWriteData (
  PRStream *stream,		/* in: play/rec stream (handle) */
  short *data,			/* in: data[] */
  long numSample);		/* in: number of samples to be written */
				/* returns: */
				/*  0=OK 1=ERROR */


/* PRClose() */
/* Close play/rec stream.*/

void PRClose (
  PRStream *stream);		/* in: play/rec stream (handle) */


#ifdef __cplusplus
}
#endif

#endif	/* #ifndef _playrec_h_ */

/* end of playrec.h */

