KallistiOS  2.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Macros | Typedefs | Functions
stream.h File Reference

Sound streaming support. More...

#include <sys/cdefs.h>
#include <arch/types.h>

Go to the source code of this file.

Macros

#define SND_STREAM_MAX   4
 The maximum number of streams that can be allocated at once.
#define SND_STREAM_BUFFER_MAX   0x10000
 The maximum buffer size for a stream.
#define SND_STREAM_INVALID   -1
 Invalid stream handle.

Typedefs

typedef int snd_stream_hnd_t
 Stream handle type.
typedef void *(* snd_stream_callback_t )(snd_stream_hnd_t hnd, int smp_req, int *smp_recv)
 Stream get data callback type.
typedef void(* snd_stream_filter_t )(snd_stream_hnd_t hnd, void *obj, int hz, int channels, void **buffer, int *samplecnt)
 Stream filter callback type.

Functions

void snd_stream_set_callback (snd_stream_hnd_t hnd, snd_stream_callback_t cb)
 Set the callback for a given 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_filter_remove (snd_stream_hnd_t hnd, snd_stream_filter_t filtfunc, void *obj)
 Remove a filter from the specified stream.
void snd_stream_prefill (snd_stream_hnd_t hnd)
 Prefill the stream buffers.
int snd_stream_init ()
 Initialize the stream system.
void snd_stream_shutdown ()
 Shut down the stream system.
snd_stream_hnd_t snd_stream_alloc (snd_stream_callback_t cb, int bufsize)
 Allocate a stream.
int snd_stream_reinit (snd_stream_hnd_t hnd, snd_stream_callback_t cb)
 Reinitialize a stream.
void snd_stream_destroy (snd_stream_hnd_t hnd)
 Destroy a stream.
void snd_stream_queue_enable (snd_stream_hnd_t hnd)
 Enable queueing on a stream.
void snd_stream_queue_disable (snd_stream_hnd_t hnd)
 Disable queueing on a stream.
void snd_stream_queue_go (snd_stream_hnd_t hnd)
 Start a stream after queueing the request.
void snd_stream_start (snd_stream_hnd_t hnd, uint32 freq, int st)
 Start a stream.
void snd_stream_stop (snd_stream_hnd_t hnd)
 Stop a stream.
int snd_stream_poll (snd_stream_hnd_t hnd)
 Poll a stream.
void snd_stream_volume (snd_stream_hnd_t hnd, int vol)
 Set the volume on the stream.

Detailed Description

Sound streaming support.

This file contains declarations for doing streams of sound. This underlies pretty much any decoded sounds you might use, including the Ogg Vorbis libraries. Note that this does not actually handle decoding, so you'll have to worry about that yourself (or use something in kos-ports).

Author:
Dan Potter

Macro Definition Documentation

#define SND_STREAM_BUFFER_MAX   0x10000

The maximum buffer size for a stream.

#define SND_STREAM_INVALID   -1

Invalid stream handle.

If a stream cannot be allocated, this will be returned.

#define SND_STREAM_MAX   4

The maximum number of streams that can be allocated at once.


Typedef Documentation

typedef void*(* snd_stream_callback_t)(snd_stream_hnd_t hnd, int smp_req, int *smp_recv)

Stream get data callback type.

Functions for providing stream data will be of this type, and can be registered with snd_stream_set_callback().

Parameters:
hndThe stream handle being referred to.
smp_reqThe number of samples requested.
smp_recvUsed to return the number of samples available.
Returns:
A pointer to the buffer of samples. If stereo, the samples should be interleaved.
typedef void(* snd_stream_filter_t)(snd_stream_hnd_t hnd, void *obj, int hz, int channels, void **buffer, int *samplecnt)

Stream filter callback type.

Functions providing filters over the stream data will be of this type, and can be set with snd_stream_filter_add().

Parameters:
hndThe stream being referred to.
objFilter user data.
hzThe frequency of the sound data.
channelsThe number of channels in the sound data.
bufferA pointer to the buffer to process. This is before any stereo separation is done. Can be changed by the filter, if appropriate.
samplecntA pointer to the number of samples. This can be modified by the filter, if appropriate.
typedef int snd_stream_hnd_t

Stream handle type.

Each stream will be assigned a handle, which will be of this type. Further operations on the stream will use the handle to identify which stream is being referred to.


Function Documentation

snd_stream_hnd_t snd_stream_alloc ( snd_stream_callback_t  cb,
int  bufsize 
)

Allocate a stream.

This function allocates a stream and sets its parameters.

Parameters:
cbThe get data callback for the stream.
bufsizeThe size of the buffer for the stream.
Returns:
A handle to the new stream on success, SND_STREAM_INVALID on failure.
void snd_stream_destroy ( snd_stream_hnd_t  hnd)

Destroy a stream.

This function destroys a previously created stream, freeing all memory associated with it.

Parameters:
hndThe stream to clean up.
void snd_stream_filter_add ( snd_stream_hnd_t  hnd,
snd_stream_filter_t  filtfunc,
void *  obj 
)

Add a filter to the specified stream.

This function adds a filter to the specified stream. The filter will be called on each block of data input to the stream from then forward.

Parameters:
hndThe stream to add the filter to.
filtfuncA pointer to the filter function.
objFilter function user data.
void snd_stream_filter_remove ( snd_stream_hnd_t  hnd,
snd_stream_filter_t  filtfunc,
void *  obj 
)

Remove a filter from the specified stream.

This function removes a filter that was previously added to the specified stream.

Parameters:
hndThe stream to remove the filter from.
filtfuncA pointer to the filter function to remove.
objThe filter function's user data. Must be the same as what was passed as obj to snd_stream_filter_add().
int snd_stream_init ( )

Initialize the stream system.

This function initializes the sound stream system and allocates memory for it as needed. Note, this is not done by the default init, so if you're using the streaming support and not using something like the kos-ports Ogg Vorbis library, you'll need to call this yourself. This will implicitly call snd_init(), so it will potentially overwrite anything going on the AICA.

Return values:
-1On failure.
0On success.
int snd_stream_poll ( snd_stream_hnd_t  hnd)

Poll a stream.

This function polls the specified stream to load more data if necessary. If using the streaming support, you must call this function periodically (most likely in a thread), or you won't get any sound output.

Parameters:
hndThe stream to poll.
Return values:
-3If NULL was returned from the callback.
-1If no callback is set, or if the state has been corrupted.
0On success.
void snd_stream_prefill ( snd_stream_hnd_t  hnd)

Prefill the stream buffers.

This function prefills the stream buffers before starting it. This is implicitly called by snd_stream_start(), so there's probably no good reason to call this yourself.

Parameters:
hndThe stream to prefill buffers on.
void snd_stream_queue_disable ( snd_stream_hnd_t  hnd)

Disable queueing on a stream.

This function disables queueing on the specified stream. This does not imply that a previously queued start on the stream will be fired if queueing was enabled before.

Parameters:
hndThe stream to disable queueing on.
void snd_stream_queue_enable ( snd_stream_hnd_t  hnd)

Enable queueing on a stream.

This function enables queueing on the specified stream. This will make it so that you must call snd_stream_queue_go() to actually start the stream, after scheduling the start. This is useful for getting something ready but not firing it right away.

Parameters:
hndThe stream to enable queueing on.
void snd_stream_queue_go ( snd_stream_hnd_t  hnd)

Start a stream after queueing the request.

This function makes the stream start once a start request has been queued, if queueing mode is enabled on the stream.

Parameters:
hndThe stream to start the queue on.
int snd_stream_reinit ( snd_stream_hnd_t  hnd,
snd_stream_callback_t  cb 
)

Reinitialize a stream.

This function reinitializes a stream, resetting its callback function.

Parameters:
hndThe stream handle to reinit.
cbThe new get data callback for the stream.
Returns:
hnd
void snd_stream_set_callback ( snd_stream_hnd_t  hnd,
snd_stream_callback_t  cb 
)

Set the callback for a given stream.

This function sets the get data callback function for a given stream, overwriting any old callback that may have been in place.

Parameters:
hndThe stream handle for the callback.
cbA pointer to the callback function.
void snd_stream_shutdown ( )

Shut down the stream system.

This function shuts down the stream system and frees the memory associated with it. This does not call snd_shutdown().

void snd_stream_start ( snd_stream_hnd_t  hnd,
uint32  freq,
int  st 
)

Start a stream.

This function starts processing the given stream, prefilling the buffers as necessary. In queueing mode, this will not start playback.

Parameters:
hndThe stream to start.
freqThe frequency of the sound.
st1 if the sound is stereo, 0 if mono.
void snd_stream_stop ( snd_stream_hnd_t  hnd)

Stop a stream.

This function stops a stream, stopping any sound playing from it. This will happen immediately, regardless of whether queueing is enabled or not.

Parameters:
hndThe stream to stop.
void snd_stream_volume ( snd_stream_hnd_t  hnd,
int  vol 
)

Set the volume on the stream.

This function sets the volume of the specified stream.

Parameters:
hndThe stream to set volume on.
volThe volume to set. Valid values are 0-255.