src/av/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 #ifndef AUDIO_H_
  22 #define AUDIO_H_
  23
  24 /**@defgroup Audio Audio Services
  25  * @{
  26  */
  27
  28 /** Plugin service identifier */
  29 #define AO_SERVICE "AUDIO"
  30
  31 /** Module name for logging. */
  32 #define AO_MODULENAME "audio"
  33
  34 /** Sample formats */
  35 enum samplefmt {
  36         AFMT_DEF,    /**< Unspecified format */
  37         AFMT_U8,     /**< Unsigned 8-bit */
  38         AFMT_S8,     /**< Signed 8-bit */
  39         AFMT_U16_LE, /**< Signed 16-bit little-endian byte order */
  40         AFMT_U16_BE, /**< Unsigned 16-bit big-endian byte order */
  41         AFMT_S16_LE, /**< Signed 16-bit little-endian byte order */
  42         AFMT_S16_BE, /**< Signed 16-bit big-endian byte order */
  43 };
  44
  45 /** Opaque type for storing AO plugin state */
  46 struct audio_data;
  47
  48 /** Audio format specifier */
  49 struct audio_format {
  50         int frequency;         /**< Number of samples per second */
  51         int channels;          /**< Number of channels in output */
  52         enum samplefmt format; /**< Format of a single sample */
  53 };
  54
  55 struct audio_output {
  56         int (*init)(int);
  57         int (*fini)(int);
  58         struct audio_data *(*open)(const char *, int);
  59         void (*close)(struct audio_data *);
  60         int (*play)(struct audio_data *, int, double);
  61         int (*stop)(int);
  62         int (*fade)(int, struct audio_data *, int, double);
  63 };
  64
  65 int audio_init(void);
  66
  67 /** Initialize audio output driver.
  68  *
  69  * @param flags Reserved.
  70  * @return 0 on successful initialization, -1 otherwise.
  71  */
  72 int ao_init(int flags);
  73
  74 /** Shutdown audio output driver.
  75  * Shuts down the audio output driver if all open sounds are closed, and all
  76  * playback is halted.  Upon successful shutdown, the driver will be in a state
  77  * suitable for re-initialization by ao_init().
  78  * Shutdown may be forced, in which case the driver should attempt to halt even
  79  * if it is not currently in a sane state to do so- i.e. open or playing sounds.
  80  * In this case, it is unspecified as to whether open sounds are closed, or
  81  * playback halted.  Even if forced, a shutdown is permitted to fail if it is
  82  * actually impossible to return to a state suitable for re-initialization.
  83  *
  84  * @param force If true, attempt shutdown even if not in a sane state to do so.
  85  * @return 0 if shutdown was successful, -1 on failure.
  86  */
  87 int ao_fini(int force);
  88
  89 #define AUD_OPEN_STREAM 0x01
  90 #define AUD_OPEN_SAMPLE 0x02
  91
  92 /** Open a resource for audio playback.
  93  * The named av resource will be opened, according to the given flags.
  94  *
  95  * @param resource VFS resource name to open.
  96  * @param flags Flags to open with.
  97  * @return Opaque pointer for subsequent operations, or NULL on failure.
  98  */
  99 struct audio_data *ao_open(const char *resource, int flags);
 100
 101 /** Close an audio resource.
 102  * The specified audio data will be unloaded/closed at the next possible
 103  * opportunity.  It is unspecified as to whether or not currently playing
 104  * sounds are stopped.
 105  *
 106  * @param data Opaque pointer as returned by ao_open()
 107  */
 108 void ao_close(struct audio_data *data);
 109
 110 /** Play audio.
 111  * The specified audio data will be played, repeating nloops times.
 112  * It is unspecified as to what happens if there are currently no free playback
 113  * channels.
 114  *
 115  * @param data Opaque pointer as returned by ao_open().
 116  * @param nloops Number of times to loop, -1 to loop infinitely.
 117  * @param volume Scale the sample volume by this amount (between 0 and 1)
 118  * @return An ID representing the playing sound, or -1 on failure.
 119  */
 120 int ao_play(struct audio_data *data, int nloops, double volume);
 121
 122 /** Stop currently playing audio.
 123  * The playing sound corresponding to id will be stopped at the earliest
 124  * possible point after this call.
 125  *
 126  * @param Playing sound ID as returned by ao_play().
 127  * @return 0 on success, or -1 if the ID does not correspond to a playing sound.
 128  */
 129 int ao_stop(int id);
 130
 131 /** "Fade" a currently playing sound into a new sound.
 132  * Similar to stopping a sound and playing a new sound, except a smooth
 133  * transition is desired.  A particular plugin is allowed to do whatever
 134  * transition it pleases.  If id does not correspond to a currently playing
 135  * sound, this is equivalent to ao_play(data, nloops), except possibly with
 136  * a transition from silence.
 137  *
 138  * @param id Playing sound ID as returned by ao_play().
 139  * @param data Opaque pointer as returned by ao_open().
 140  * @param nloops Number of timse to loop, -1 to loop infinitely.
 141  * @param volume Scale the sample volume by this amount (between 0 and 1)
 142  * @return An ID representing the new playing sound, or -1 on failure.
 143  */
 144 int ao_fade(int id, struct audio_data *data, int nloops, double volume);
 145
 146 /*@}*/
 147
 148 #endif