KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
stream.h
Go to the documentation of this file.
1 /* KallistiOS ##version##
2 
3  dc/sound/stream.h
4  Copyright (C) 2002, 2004 Dan Potter
5 
6 */
7 
8 /** \file dc/sound/stream.h
9  \brief Sound streaming support.
10 
11  This file contains declarations for doing streams of sound. This underlies
12  pretty much any decoded sounds you might use, including the Ogg Vorbis
13  libraries. Note that this does not actually handle decoding, so you'll have
14  to worry about that yourself (or use something in kos-ports).
15 
16  \author Dan Potter
17 */
18 
19 #ifndef __DC_SOUND_STREAM_H
20 #define __DC_SOUND_STREAM_H
21 
22 #include <sys/cdefs.h>
23 __BEGIN_DECLS
24 
25 #include <arch/types.h>
26 
27 /** \brief The maximum number of streams that can be allocated at once. */
28 #define SND_STREAM_MAX 4
29 
30 /** \brief The maximum buffer size for a stream. */
31 #define SND_STREAM_BUFFER_MAX 0x10000
32 
33 /** \brief Stream handle type.
34 
35  Each stream will be assigned a handle, which will be of this type. Further
36  operations on the stream will use the handle to identify which stream is
37  being referred to.
38 */
39 typedef int snd_stream_hnd_t;
40 
41 /** \brief Invalid stream handle.
42 
43  If a stream cannot be allocated, this will be returned.
44 */
45 #define SND_STREAM_INVALID -1
46 
47 /** \brief Stream get data callback type.
48 
49  Functions for providing stream data will be of this type, and can be
50  registered with snd_stream_set_callback().
51 
52  \param hnd The stream handle being referred to.
53  \param smp_req The number of samples requested.
54  \param smp_recv Used to return the number of samples available.
55  \return A pointer to the buffer of samples. If stereo, the
56  samples should be interleaved.
57 */
58 typedef void *(*snd_stream_callback_t)(snd_stream_hnd_t hnd, int smp_req,
59  int *smp_recv);
60 
61 /** \brief Set the callback for a given stream.
62 
63  This function sets the get data callback function for a given stream,
64  overwriting any old callback that may have been in place.
65 
66  \param hnd The stream handle for the callback.
67  \param cb A pointer to the callback function.
68 */
70 
71 /* Add an effect filter to the sound stream chain. When the stream
72  buffer filler needs more data, it starts out by calling the initial
73  callback (set above). It then calls each function in the effect
74  filter chain, which can modify the buffer and the amount of data
75  available as well. Filters persist across multiple calls to _init()
76  but will be emptied by _shutdown(). */
77 
78 /** \brief Stream filter callback type.
79 
80  Functions providing filters over the stream data will be of this type, and
81  can be set with snd_stream_filter_add().
82 
83  \param hnd The stream being referred to.
84  \param obj Filter user data.
85  \param hz The frequency of the sound data.
86  \param channels The number of channels in the sound data.
87  \param buffer A pointer to the buffer to process. This is before
88  any stereo separation is done. Can be changed by the
89  filter, if appropriate.
90  \param samplecnt A pointer to the number of samples. This can be
91  modified by the filter, if appropriate.
92 */
93 typedef void (*snd_stream_filter_t)(snd_stream_hnd_t hnd, void *obj, int hz,
94  int channels, void **buffer,
95  int *samplecnt);
96 
97 /** \brief Add a filter to the specified stream.
98 
99  This function adds a filter to the specified stream. The filter will be
100  called on each block of data input to the stream from then forward.
101 
102  \param hnd The stream to add the filter to.
103  \param filtfunc A pointer to the filter function.
104  \param obj Filter function user data.
105 */
107  void *obj);
108 
109 /** \brief Remove a filter from the specified stream.
110 
111  This function removes a filter that was previously added to the specified
112  stream.
113 
114  \param hnd The stream to remove the filter from.
115  \param filtfunc A pointer to the filter function to remove.
116  \param obj The filter function's user data. Must be the same as
117  what was passed as obj to snd_stream_filter_add().
118 */
120  snd_stream_filter_t filtfunc, void *obj);
121 
122 /** \brief Prefill the stream buffers.
123 
124  This function prefills the stream buffers before starting it. This is
125  implicitly called by snd_stream_start(), so there's probably no good reason
126  to call this yourself.
127 
128  \param hnd The stream to prefill buffers on.
129 */
131 
132 /** \brief Initialize the stream system.
133 
134  This function initializes the sound stream system and allocates memory for
135  it as needed. Note, this is not done by the default init, so if you're using
136  the streaming support and not using something like the kos-ports Ogg Vorbis
137  library, you'll need to call this yourself. This will implicitly call
138  snd_init(), so it will potentially overwrite anything going on the AICA.
139 
140  \retval -1 On failure.
141  \retval 0 On success.
142 */
143 int snd_stream_init();
144 
145 /** \brief Shut down the stream system.
146 
147  This function shuts down the stream system and frees the memory associated
148  with it. This does not call snd_shutdown().
149 */
150 void snd_stream_shutdown();
151 
152 /** \brief Allocate a stream.
153 
154  This function allocates a stream and sets its parameters.
155 
156  \param cb The get data callback for the stream.
157  \param bufsize The size of the buffer for the stream.
158  \return A handle to the new stream on success,
159  SND_STREAM_INVALID on failure.
160 */
162 
163 /** \brief Reinitialize a stream.
164 
165  This function reinitializes a stream, resetting its callback function.
166 
167  \param hnd The stream handle to reinit.
168  \param cb The new get data callback for the stream.
169  \return hnd
170 */
172 
173 /** \brief Destroy a stream.
174 
175  This function destroys a previously created stream, freeing all memory
176  associated with it.
177 
178  \param hnd The stream to clean up.
179 */
181 
182 /** \brief Enable queueing on a stream.
183 
184  This function enables queueing on the specified stream. This will make it so
185  that you must call snd_stream_queue_go() to actually start the stream, after
186  scheduling the start. This is useful for getting something ready but not
187  firing it right away.
188 
189  \param hnd The stream to enable queueing on.
190 */
192 
193 /** \brief Disable queueing on a stream.
194 
195  This function disables queueing on the specified stream. This does not imply
196  that a previously queued start on the stream will be fired if queueing was
197  enabled before.
198 
199  \param hnd The stream to disable queueing on.
200 */
202 
203 /** \brief Start a stream after queueing the request.
204 
205  This function makes the stream start once a start request has been queued,
206  if queueing mode is enabled on the stream.
207 
208  \param hnd The stream to start the queue on.
209 */
211 
212 /** \brief Start a stream.
213 
214  This function starts processing the given stream, prefilling the buffers as
215  necessary. In queueing mode, this will not start playback.
216 
217  \param hnd The stream to start.
218  \param freq The frequency of the sound.
219  \param st 1 if the sound is stereo, 0 if mono.
220 */
221 void snd_stream_start(snd_stream_hnd_t hnd, uint32 freq, int st);
222 
223 /** \brief Stop a stream.
224 
225  This function stops a stream, stopping any sound playing from it. This will
226  happen immediately, regardless of whether queueing is enabled or not.
227 
228  \param hnd The stream to stop.
229 */
231 
232 /** \brief Poll a stream.
233 
234  This function polls the specified stream to load more data if necessary. If
235  using the streaming support, you must call this function periodically (most
236  likely in a thread), or you won't get any sound output.
237 
238  \param hnd The stream to poll.
239  \retval -3 If NULL was returned from the callback.
240  \retval -1 If no callback is set, or if the state has been
241  corrupted.
242  \retval 0 On success.
243 */
245 
246 /** \brief Set the volume on the stream.
247 
248  This function sets the volume of the specified stream.
249 
250  \param hnd The stream to set volume on.
251  \param vol The volume to set. Valid values are 0-255.
252 */
253 void snd_stream_volume(snd_stream_hnd_t hnd, int vol);
254 
255 __END_DECLS
256 
257 #endif /* __DC_SOUND_STREAM_H */
258 
Common integer types.
void *(* snd_stream_callback_t)(snd_stream_hnd_t hnd, int smp_req, int *smp_recv)
Stream get data callback type.
Definition: stream.h:58
void snd_stream_volume(snd_stream_hnd_t hnd, int vol)
Set the volume on the stream.
void snd_stream_stop(snd_stream_hnd_t hnd)
Stop a stream.
void(* snd_stream_filter_t)(snd_stream_hnd_t hnd, void *obj, int hz, int channels, void **buffer, int *samplecnt)
Stream filter callback type.
Definition: stream.h:93
int snd_stream_reinit(snd_stream_hnd_t hnd, snd_stream_callback_t cb)
Reinitialize a stream.
void snd_stream_queue_enable(snd_stream_hnd_t hnd)
Enable queueing on a stream.
void snd_stream_prefill(snd_stream_hnd_t hnd)
Prefill the stream buffers.
void snd_stream_start(snd_stream_hnd_t hnd, uint32 freq, int st)
Start a stream.
void snd_stream_filter_remove(snd_stream_hnd_t hnd, snd_stream_filter_t filtfunc, void *obj)
Remove a filter from the specified stream.
void snd_stream_set_callback(snd_stream_hnd_t hnd, snd_stream_callback_t cb)
Set the callback for a given stream.
unsigned long uint32
32-bit unsigned integer
Definition: types.h:28
snd_stream_hnd_t snd_stream_alloc(snd_stream_callback_t cb, int bufsize)
Allocate a stream.
void snd_stream_filter_add(snd_stream_hnd_t hnd, snd_stream_filter_t filtfunc, void *obj)
Add a filter to the specified stream.
void snd_stream_queue_disable(snd_stream_hnd_t hnd)
Disable queueing on a stream.
int snd_stream_init()
Initialize the stream system.
void snd_stream_shutdown()
Shut down the stream system.
int snd_stream_hnd_t
Stream handle type.
Definition: stream.h:39
void snd_stream_destroy(snd_stream_hnd_t hnd)
Destroy a stream.
void snd_stream_queue_go(snd_stream_hnd_t hnd)
Start a stream after queueing the request.
int snd_stream_poll(snd_stream_hnd_t hnd)
Poll a stream.