2 * Declarations for audio facilities
4 /* 2ooM: The Master of Orion II Reverse Engineering Project
5 * Copyright (C) 2006 Nick Bowler
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.
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.
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
24 /**@defgroup Audio Audio Services
28 /** Plugin service identifier */
29 #define AO_SERVICE "AUDIO"
31 /** Module name for logging. */
32 #define AO_MODULENAME "audio"
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 */
45 /** Opaque type for storing AO plugin state */
48 /** Audio format specifier */
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 */
58 struct audio_data
*(*open
)(const char *, int);
59 void (*close
)(struct audio_data
*);
60 int (*play
)(struct audio_data
*, int, double);
62 int (*fade
)(int, struct audio_data
*, int, double);
67 /** Initialize audio output driver.
69 * @param flags Reserved.
70 * @return 0 on successful initialization, -1 otherwise.
72 int ao_init(int flags
);
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.
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.
87 int ao_fini(int force
);
89 #define AUD_OPEN_STREAM 0x01
90 #define AUD_OPEN_SAMPLE 0x02
92 /** Open a resource for audio playback.
93 * The named av resource will be opened, according to the given flags.
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.
99 struct audio_data
*ao_open(const char *resource
, int flags
);
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.
106 * @param data Opaque pointer as returned by ao_open()
108 void ao_close(struct audio_data
*data
);
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
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.
120 int ao_play(struct audio_data
*data
, int nloops
, double volume
);
122 /** Stop currently playing audio.
123 * The playing sound corresponding to id will be stopped at the earliest
124 * possible point after this call.
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.
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.
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.
144 int ao_fade(int id
, struct audio_data
*data
, int nloops
, double volume
);