src/audio/audio.h

   1 /** @file audio.h
   2  *  Declarations for audio facilities
   3 */
   4 /*  2ooM: The Master of Orion II Reverse Engineering Project
   5  *  Copyright (C) 2006 Nick Bowler
   6  *
   7  *  This program is free software; you can redistribute it and/or modify
   8  *  it under the terms of the GNU General Public License as published by
   9  *  the Free Software Foundation; either version 2 of the License, or
  10  *  (at your option) any later version.
  11  *
  12  *  This program is distributed in the hope that it will be useful,
  13  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  *  GNU General Public License for more details.
  16  *
  17  *  You should have received a copy of the GNU General Public License
  18  *  along with this program; if not, write to the Free Software
  19  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  20  **
  21  * $HeadURL$
  22  * $Date$
  23  * $Revision$
  24  * $Author$
  25  */
  26
  27 /**@defgroup Audio Audio Services
  28  * @{
  29  */
  30
  31 /** Plugin service identifier */
  32 #define AO_SERVICE "AUDIO"
  33
  34 /** Module name for logging. */
  35 #define AO_MODULENAME "audio"
  36
  37 /** Sample formats */
  38 enum samplefmt {
  39         AFMT_DEF,    /**< Unspecified format */
  40         AFMT_U8,     /**< Unsigned 8-bit */
  41         AFMT_S8,     /**< Signed 8-bit */
  42         AFMT_U16_LE, /**< Signed 16-bit little-endian byte order */
  43         AFMT_U16_BE, /**< Unsigned 16-bit big-endian byte order */
  44         AFMT_S16_LE, /**< Signed 16-bit little-endian byte order */
  45         AFMT_S16_BE, /**< Signed 16-bit big-endian byte order */
  46 };
  47
  48 /** Opaque type for storing AO plugin state */
  49 struct audio_data;
  50
  51 /** Audio format specifier */
  52 struct audio_format {
  53         int frequency;         /**< Number of samples per second */
  54         int channels;          /**< Number of channels in output */
  55         enum samplefmt format; /**< Format of a single sample */
  56 };
  57
  58 struct audio_output {
  59         int (*init)(int);
  60         int (*play)(struct audio_data *, int);
  61 };
  62
  63 /** Initialize audio output driver.
  64  *
  65  * @param flags Reserved.
  66  * @return 0 on successful initialization, -1 otherwise.
  67  */
  68 int ao_init(int flags);
  69
  70 /** Shutdown audio output driver.
  71  * Shuts down the audio output driver if all open sounds are closed, and all
  72  * playback is halted.  Upon successful shutdown, the driver will be in a state
  73  * suitable for re-initialization by ao_init().
  74  * Shutdown may be forced, in which case the driver should attempt to halt even
  75  * if it is not currently in a sane state to do so- i.e. open or playing sounds.
  76  * In this case, it is unspecified as to whether open sounds are closed, or
  77  * playback halted.  Even if forced, a shutdown is permitted to fail if it is
  78  * actually impossible to return to a state suitable for re-initialization.
  79  *
  80  * @param force If true, attempt shutdown even if not in a sane state to do so.
  81  * @return 0 if shutdown was successful, -1 on failure.
  82  */
  83 int ao_fini(int force);
  84
  85 #define AUD_OPEN_STREAM 0x01
  86 #define AUD_OPEN_SAMPLE 0x02
  87
  88 /** Open a resource for audio playback.
  89  * The named av resource will be opened, according to the given flags.
  90  *
  91  * @param resource VFS resource name to open.
  92  * @param flags Flags to open with.
  93  * @return Opaque pointer for subsequent operations, or NULL on failure.
  94  */
  95 struct audio_data *ao_open(const char *resource, int flags);
  96
  97 /** Close an audio resource.
  98  * The specified audio data will be unloaded/closed at the next possible
  99  * opportunity.  It is unspecified as to whether or not currently playing
 100  * sounds are stopped.
 101  *
 102  * @param data Opaque pointer as returned by ao_open()
 103  */
 104 void ao_close(struct audio_data *data);
 105
 106 /** Play audio.
 107  * The specified audio data will be played, repeating nloops times.
 108  * It is unspecified as to what happens if there are currently no free playback
 109  * channels.
 110  *
 111  * @param data Opaque pointer as returned by ao_open().
 112  * @param nloops Number of times to loop, -1 to loop infinitely.
 113  * @return An ID representing the playing sound, or -1 on failure.
 114  */
 115 int ao_play(struct audio_data *data, int nloops);
 116
 117 /** Stop currently playing audio.
 118  * The playing sound corresponding to id will be stopped at the earliest
 119  * possible point after this call.
 120  *
 121  * @param Playing sound ID as returned by ao_play().
 122  * @return 0 on success, or -1 if the ID does not correspond to a playing sound.
 123  */
 124 int ao_stop(int id);
 125
 126 /** "Fade" a currently playing sound into a new sound.
 127  * Similar to stopping a sound and playing a new sound, except a smooth
 128  * transition is desired.  A particular plugin is allowed to do whatever
 129  * transition it pleases.  If id does not correspond to a currently playing
 130  * sound, this is equivalent to ao_play(data, nloops), except possibly with
 131  * a transition from silence.
 132  *
 133  * @param id Playing sound ID as returned by ao_play().
 134  * @param data Opaque pointer as returned by ao_open().
 135  * @param nloops Number of timse to loop, -1 to loop infinitely.
 136  * @return An ID representing the new playing sound, or -1 on failure.
 137  */
 138 int ao_fade(int id, struct audio_data *data, int nloops);
 139
 140 /*@}*/