KallistiOS  2.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
sfxmgr.h
Go to the documentation of this file.
1 /* KallistiOS 2.0.0
2 
3  dc/sound/sfxmgr.h
4  Copyright (C) 2002 Dan Potter
5 
6 */
7 
8 /** \file dc/sound/sfxmgr.h
9  \brief Basic sound effect support.
10 
11  This file contains declarations for doing simple sound effects. This code is
12  only usable for simple WAV files containing either 16-bit samples (stereo or
13  mono) or Yamaha ADPCM (4-bits, stereo or mono). Also, all sounds played in
14  this manner must be at most 65534 samples in length, as this does not handle
15  buffer chaining or anything else complex. For more interesting stuff, you
16  should probably look at the sound stream stuff instead.
17 
18  \author Dan Potter
19 */
20 
21 #ifndef __DC_SOUND_SFXMGR_H
22 #define __DC_SOUND_SFXMGR_H
23 
24 #include <sys/cdefs.h>
25 __BEGIN_DECLS
26 
27 #include <arch/types.h>
28 
29 /** \brief Sound effect handle type.
30 
31  Each loaded sound effect will be assigned one of these, which is to be used
32  for operations related to the effect, including playing it or unloading it.
33 */
34 typedef uint32 sfxhnd_t;
35 
36 /** \brief Invalid sound effect handle value.
37 
38  If a sound effect cannot be loaded, this value will be returned as the error
39  condition.
40 */
41 #define SFXHND_INVALID 0
42 
43 /** \brief Load a sound effect.
44 
45  This function loads a sound effect from a WAV file and returns a handle to
46  it. The sound effect can be either stereo or mono, and must either be 16-bit
47  uncompressed PCM samples or 4-bit Yamaha ADPCM.
48 
49  \param fn The file to load.
50  \return A handle to the sound effect on success. On error,
51  SFXHND_INVALID is returned.
52 */
53 sfxhnd_t snd_sfx_load(const char *fn);
54 
55 /** \brief Unload a sound effect.
56 
57  This function unloads a previously loaded sound effect, and frees the memory
58  associated with it.
59 
60  \param idx A handle to the sound effect to unload.
61 */
62 void snd_sfx_unload(sfxhnd_t idx);
63 
64 /** \brief Unload all loaded sound effects.
65 
66  This function unloads all previously loaded sound effect, and frees the
67  memory associated with them.
68 */
69 void snd_sfx_unload_all();
70 
71 /** \brief Play a sound effect.
72 
73  This function plays a loaded sound effect with the specified volume (for
74  both stereo or mono) and panning values (for mono sounds only).
75 
76  \param idx The handle to the sound effect to play.
77  \param vol The volume to play at (between 0 and 255).
78  \param pan The panning value of the sound effect. 0 is all the
79  way to the left, 128 is center, 255 is all the way
80  to the right.
81 
82  \return The channel used to play the sound effect (or the
83  left channel in the case of a stereo sound, the
84  right channel will be the next one) on success, or
85  -1 on failure.
86 */
87 int snd_sfx_play(sfxhnd_t idx, int vol, int pan);
88 
89 /** \brief Play a sound effect on a specific channel.
90 
91  This function works similar to snd_sfx_play(), but allows you to specify the
92  channel to play on. No error checking is done with regard to the channel, so
93  be sure its safe to play on that channel before trying.
94 
95  \param chn The channel to play on (or in the case of stereo,
96  the left channel).
97  \param idx The handle to the sound effect to play.
98  \param vol The volume to play at (between 0 and 255).
99  \param pan The panning value of the sound effect. 0 is all the
100  way to the left, 128 is center, 255 is all the way
101  to the right.
102 
103  \return chn
104 */
105 int snd_sfx_play_chn(int chn, sfxhnd_t idx, int vol, int pan);
106 
107 /** \brief Stop a single channel of sound.
108 
109  This function stops the specified channel of sound from playing. It does no
110  checking to make sure that a sound effect is playing on the channel
111  specified, and thus can be used even if you're using the channel for some
112  other purpose than sound effects.
113 
114  \param chn The channel to stop.
115 */
116 void snd_sfx_stop(int chn);
117 
118 /** \brief Stop all channels playing sound effects.
119 
120  This function stops all channels currently allocated to sound effects from
121  playing. It does not affect channels allocated for use by something other
122  than sound effects..
123 */
124 void snd_sfx_stop_all();
125 
126 /** \brief Allocate a sound channel for use outside the sound effect system.
127 
128  This function finds and allocates a channel for use for things other than
129  sound effects. This is useful for, for instance, the streaming code.
130 
131  \returns The allocated channel on success, -1 on failure.
132 */
133 int snd_sfx_chn_alloc();
134 
135 /** \brief Free a previously allocated channel.
136 
137  This function frees a channel that was allocated with snd_sfx_chn_alloc(),
138  returning it to the pool of available channels for sound effect use.
139 
140  \param chn The channel to free.
141 */
142 void snd_sfx_chn_free(int chn);
143 
144 __END_DECLS
145 
146 #endif /* __DC_SOUND_SFXMGR_H */
147 
Generated by   doxygen 1.8.1.1