/* midasstr.h * * MIDAS stream library * * $Id: midasstr.h,v 1.5 1997/01/16 19:31:53 pekangas Exp $ * * Copyright 1996,1997 Housemarque Inc. * * This file is part of the MIDAS Sound System, and may only be * used, modified and distributed under the terms of the MIDAS * Sound System license, LICENSE.TXT. By continuing to use, * modify or distribute this file you indicate that you have * read the license and understand and accept it fully. */ #ifndef __midasstr_h #define __midasstr_h /* Hack for Linux: (FIXME) */ #ifdef __LINUX__ #include #endif /****************************************************************************\ * enum strStreamMode * ------------------ * Description: Stream playing mode \****************************************************************************/ enum strStreamMode { strStreamPlayFile = 1, strStreamCallback, strStreamPoll }; /****************************************************************************\ * struct strStream * ---------------- * Description: Stream playing structure \****************************************************************************/ typedef struct _strStream { unsigned sdChannel; /* channel number for the stream */ uchar *buffer; /* pointer to stream buffer */ unsigned bufferSamples; /* buffer length in samples */ unsigned bufferBytes; /* buffer length in bytes */ unsigned bufferWritePos; /* buffer write position */ uchar *fileBuffer; /* file reading buffer */ unsigned fileBufferBytes; /* file reading buffer size */ unsigned sampleSize; /* size of one sample in bytes */ int streamMode; /* see enum strStreamMode */ fileHandle f; /* stream file handle */ ulong fileLength; /* stream file length in bytes */ ulong fileLeft; /* number of bytes left in file */ int loop; /* 1 if the stream loops */ volatile int threadExitFlag; /* thread exit flag */ unsigned threadDelay; /* delay between polling in thread */ void (CALLING *callback)(uchar *buffer, struct _strStream *stream); #ifdef __LINUX__ pthread_t playerThread; /* player thread */ #endif /* stream playing callback */ uchar bufferClearVal; /* the value that should be used to clear the buffer */ uchar filler[3]; } strStream; #ifdef __cplusplus extern "C" { #endif /****************************************************************************\ * * Function: int strInit(SoundDevice *SD) * * Description: Initializes the stream library * * Input: SoundDevice *SD Pointer to the Sound Device that will * be used for playing the streams * * Returns: MIDAS error code * \****************************************************************************/ int CALLING strInit(SoundDevice *SD); /****************************************************************************\ * * Function: int strClose(void) * * Description: Uninitializes the stream library * * Returns: MIDAS error code * \****************************************************************************/ int CALLING strClose(void); /****************************************************************************\ * * Function: int strPlayStreamFile(unsigned channel, char *fileName, * unsigned sampleType, ulong sampleRate, * unsigned bufferLength, int loop, strStream **stream) * * Description: Starts playing a digital sound stream from a file. Creates a * new thread that will take care of reading the file and feeding * it to the stream buffer * * Input: unsigned channel channel number for the stream * char *fileName stream file name * unsigned sampleType stream sample type * ulong sampleRate sampling rate * unsigned bufferLength stream buffer length in milliseconds * int loop 1 if the stream should be looped, * 0 if not * strStream **stream pointer to stream state pointer * * Returns: MIDAS error code. Pointer to the stream state structure will * be written to *stream * \****************************************************************************/ int CALLING strPlayStreamFile(unsigned channel, char *fileName, unsigned sampleType, ulong sampleRate, unsigned bufferLength, int loop, strStream **stream); /****************************************************************************\ * * Function: int strPlayStreamPolling(unsigned channel, * unsigned sampleType, ulong sampleRate, * unsigned bufferLength, strStream **stream) * * Description: Starts playing a stream in polling mode. Use * strFeedStreamData() to feed the stream data to the player * * Input: unsigned channel channel number for the stream * unsigned sampleType stream sample type * ulong sampleRate stream sampling rate * unsigned bufferLength stream buffer length in milliseconds * strStream **stream pointer to stream state pointer * * Returns: MIDAS error code. Pointer to the stream state structure will * be written to *stream * \****************************************************************************/ int CALLING strPlayStreamPolling(unsigned channel, unsigned sampleType, ulong sampleRate, unsigned bufferLength, strStream **stream); /****************************************************************************\ * * Function: int strPlayStreamCallback(unsigned sampleType, * ulong sampleRate, unsigned bufferBytes, * void (CALLING *callback)(uchar *buffer, strStream *stream)) * * Description: Starts playing a stream with a callback. * * Input: unsigned sampleType stream sample type * ulong sampleRate stream sampling rate * unsigned bufferBytes stream buffer size _IN BYTES_ * ... *callback stream player callback * strStream **stream pointer to stream state pointer * * Returns: MIDAS error code. Pointer to the stream state structure will * be written to *stream * * Notes: The callback function will be called each time the whole * stream buffer needs to be filled. It receives as an argument * a pointer to the buffer, and the stream state pointer. * * The function will be called from inside the mixing routine, * so it should return relatively rapidly - do not use this * function for, for example, loading data from disc. * \****************************************************************************/ int CALLING strPlayStreamCallback(unsigned sampleType, ulong sampleRate, unsigned bufferBytes, void (CALLING *callback)(uchar *buffer, strStream *stream)); /****************************************************************************\ * * Function: int strStopStream(strStream *stream) * * Description: Stops playing a stream. This function will also destroy the * playback thread for stream file playback. * * Input: strStream *stream stream state pointer for the stream * * Returns: MIDAS error code. * \****************************************************************************/ int CALLING strStopStream(strStream *stream); /****************************************************************************\ * * Function: int strFeedStreamData(strStream *stream, uchar *data, * unsigned numBytes, int feedAll, unsigned *numFed) * * Description: Feeds sample data to a stream that is being played in polling * mode. * * Input: strStream *stream stream state pointer from * strPlayStreamPolling() * uchar *data pointer to stream data * unsigned numBytes number of bytes of data to feed. Note! * This must be a multiple of the stream * sample size * int feedAll 1 if all data should be fed in all * circumstances. The function will block * the current thread if this flag is 1 * until all data is fed. * unsigned *numFed pointer to a variable that will * contain the number of bytes actually * fed * * Returns: MIDAS error code. The number of bytes of data actually fed is * written to *numFed. * \****************************************************************************/ int CALLING strFeedStreamData(strStream *stream, uchar *data, unsigned numBytes, int feedAll, unsigned *numFed); /****************************************************************************\ * * Function: int strSetStreamRate(strStream *stream, ulong sampleRate) * * Description: Changes the sampling rate for a stream * * Input: strStream *stream stream state pointer * ulong sampleRate new sampling rate in Hz * * Returns: MIDAS error code * \****************************************************************************/ int CALLING strSetStreamRate(strStream *stream, ulong sampleRate); /****************************************************************************\ * * Function: int strSetStreamVolume(strStream *stream, unsigned volume) * * Description: Changes the playback volume for a stream (the default is 64). * * Input: strStream *stream stream state pointer * unsigned volume new volume (0-64) * * Returns: MIDAS error code. * \****************************************************************************/ int CALLING strSetStreamVolume(strStream *stream, unsigned volume); /****************************************************************************\ * * Function: int strSetStreamPanning(strStream *stream, int panning) * * Description: Changes the panning for a stream (the default is middle). * * Input: strStream *stream stream state pointer * int panning new panning position * * Returns: MIDAS error code. * \****************************************************************************/ int CALLING strSetStreamPanning(strStream *stream, int panning); /****************************************************************************\ * * Function: int strIsStreamFinished(strStream *stream, int *finished) * * Description: Checks whether a given stream has reached the end of the * stream file or not. Only applies to streams played from a * file. * * Input: strStream *stream stream state pointer * int *finished pointer to result variable * * Returns: MIDAS error code. If the stream is finished, 1 will be written * to *finished, otherwise *finished will contain 0. * \****************************************************************************/ int CALLING strIsStreamFinished(strStream *stream, int *finished); #ifdef __cplusplus } #endif #endif /* #ifdef __midasstr_h */ /* * $Log: midasstr.h,v $ * Revision 1.5 1997/01/16 19:31:53 pekangas * Fixed to compile with Linux GCC (but do they work?) * * Revision 1.4 1997/01/16 18:41:59 pekangas * Changed copyright messages to Housemarque * * Revision 1.3 1997/01/16 18:25:08 pekangas * Implemented strSetStreamRate, strSetStreamVolume and strSetStreamPanning * * Revision 1.2 1996/09/28 06:39:46 jpaana * Converted from CR/LF and fixed some typos * * Revision 1.1 1996/09/22 23:17:48 pekangas * Initial revision * */