Streaming audio playback and management More...

Files
file	stream.h
	Sound streaming support.

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 size_t(*	snd_stream_callback_direct_t) (snd_stream_hnd_t hnd, uintptr_t left, uintptr_t right, size_t size_req)
	Direct stream data transfer 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_set_callback_direct (snd_stream_hnd_t hnd, snd_stream_callback_direct_t cb)
	Set the callback for a given stream with direct transfer.

void	snd_stream_set_userdata (snd_stream_hnd_t hnd, void *d)
	Set the user data for a given stream.

void *	snd_stream_get_userdata (snd_stream_hnd_t hnd)
	Get the user data 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 (void)
	Initialize the stream system.

int	snd_stream_init_ex (int channels, size_t buffer_size)
	Initialize the stream system with limits.

void	snd_stream_shutdown (void)
	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 16-bit PCM stream.

void	snd_stream_start_pcm8 (snd_stream_hnd_t hnd, uint32 freq, int st)
	Start a 8-bit PCM stream.

void	snd_stream_start_adpcm (snd_stream_hnd_t hnd, uint32 freq, int st)
	Start a 4-bit ADPCM 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.

void	snd_stream_pan (snd_stream_hnd_t hnd, int left_pan, int right_pan)
	Set the panning on the stream.

Detailed Description

Streaming audio playback and management

Macro Definition Documentation

◆ SND_STREAM_BUFFER_MAX

#define SND_STREAM_BUFFER_MAX 0x10000

The maximum buffer size for a stream.

◆ SND_STREAM_INVALID

#define SND_STREAM_INVALID -1

Invalid stream handle.

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

◆ SND_STREAM_MAX

#define SND_STREAM_MAX 4

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

Typedef Documentation

◆ snd_stream_callback_direct_t

typedef size_t(* snd_stream_callback_direct_t) (snd_stream_hnd_t hnd, uintptr_t left, uintptr_t right, size_t size_req)

Direct stream data transfer callback type.

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

Parameters

hnd	The stream handle being referred to.
left	Left channel buffer address on AICA side.
right	Right channel buffer address on AICA side.
size_req	Requested size for each channel.

Return values

-1	On failure.
size_recv	On success, received size.

◆ snd_stream_callback_t

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

hnd	The stream handle being referred to.
smp_req	The number of samples requested.
smp_recv	Used to return the number of samples available.

Returns: A pointer to the buffer of samples. If stereo, the samples should be interleaved. For best performance use 32-byte aligned pointer.

◆ snd_stream_filter_t

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

hnd	The stream being referred to.
obj	Filter user data.
hz	The frequency of the sound data.
channels	The number of channels in the sound data.
buffer	A pointer to the buffer to process. This is before any stereo separation is done. Can be changed by the filter, if appropriate.
samplecnt	A pointer to the number of samples. This can be modified by the filter, if appropriate.

◆ snd_stream_hnd_t

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_alloc()

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

cb	The get data callback for the stream.
bufsize	The size of the buffer for each channel of the stream.

Returns: A handle to the new stream on success, SND_STREAM_INVALID on failure.

◆ snd_stream_destroy()

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

hnd	The stream to clean up.

◆ snd_stream_filter_add()

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.

When the stream buffer filler needs more data, it starts out by calling the initial callback (set above). It then calls each function in the effect filter chain, which can modify the buffer and the amount of data available as well. Filters persist across multiple calls to _init() but will be emptied by _shutdown().

Parameters

hnd	The stream to add the filter to.
filtfunc	A pointer to the filter function.
obj	Filter function user data.

◆ snd_stream_filter_remove()

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

hnd	The stream to remove the filter from.
filtfunc	A pointer to the filter function to remove.
obj	The filter function's user data. Must be the same as what was passed as obj to snd_stream_filter_add().

◆ snd_stream_get_userdata()

void * snd_stream_get_userdata ( snd_stream_hnd_t hnd )

Get the user data for a given stream.

This function retrieves the set user data pointer for a given stream.

Parameters

hnd	The stream handle to look up.

Returns: The user data pointer set for this stream or NULL if no data pointer has been set.

◆ snd_stream_init()

int snd_stream_init ( void )

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

-1	On failure.
0	On success.

◆ snd_stream_init_ex()

int snd_stream_init_ex	(	int	channels,
		size_t	buffer_size )

Initialize the stream system with limits.

The same as snd_stream_init but it can either reduce or not allocate the buffer for splitting the stereo stream at all.

Parameters

channels	Max channels for any streams.
buffer_size	Max channel buffer size for any streams.

Return values

-1	On failure.
0	On success.

◆ snd_stream_pan()

void snd_stream_pan	(	snd_stream_hnd_t	hnd,
		int	left_pan,
		int	right_pan )

Set the panning on the stream.

This function sets the panning of the specified stream.

Parameters

hnd	The stream to set volume on.
left_pan	The left panning to set. Valid values are 0-255.
right_pan	The right panning to set. Valid values are 0-255.

◆ snd_stream_poll()

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

hnd	The stream to poll.

Return values

-3	If NULL was returned from the callback.
-1	If no callback is set, or if the state has been corrupted.
0	On success.

◆ snd_stream_prefill()

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

hnd	The stream to prefill buffers on.

◆ snd_stream_queue_disable()

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

hnd	The stream to disable queueing on.

◆ snd_stream_queue_enable()

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

hnd	The stream to enable queueing on.

◆ snd_stream_queue_go()

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

hnd	The stream to start the queue on.

◆ snd_stream_reinit()

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

hnd	The stream handle to reinit.
cb	The new get data callback for the stream.

Returns: hnd

◆ snd_stream_set_callback()

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

hnd	The stream handle for the callback.
cb	A pointer to the callback function.

◆ snd_stream_set_callback_direct()

void snd_stream_set_callback_direct	(	snd_stream_hnd_t	hnd,
		snd_stream_callback_direct_t	cb )

Set the callback for a given stream with direct transfer.

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

Parameters

hnd	The stream handle for the callback.
cb	A pointer to the callback function.

◆ snd_stream_set_userdata()

void snd_stream_set_userdata	(	snd_stream_hnd_t	hnd,
		void *	d )

Set the user data for a given stream.

This function sets the user data pointer for the given stream, overwriting any existing one that may have been in place. This is designed to allow the user the ability to associate a piece of data with the stream for instance to assist in identifying what sound is playing on a stream. The driver does not attempt to use this data in any way.

Parameters

hnd	The stream handle to look up.
d	A pointer to the user data.

◆ snd_stream_shutdown()

void snd_stream_shutdown ( void )

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().

◆ snd_stream_start()

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

Start a 16-bit PCM stream.

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

Parameters

hnd	The stream to start.
freq	The frequency of the sound.
st	1 if the sound is stereo, 0 if mono.

◆ snd_stream_start_adpcm()

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

Start a 4-bit ADPCM stream.

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

Parameters

hnd	The stream to start.
freq	The frequency of the sound.
st	1 if the sound is stereo, 0 if mono.

◆ snd_stream_start_pcm8()

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

Start a 8-bit PCM stream.

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

Parameters

hnd	The stream to start.
freq	The frequency of the sound.
st	1 if the sound is stereo, 0 if mono.

◆ snd_stream_stop()

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

hnd	The stream to stop.

◆ snd_stream_volume()

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

hnd	The stream to set volume on.
vol	The volume to set. Valid values are 0-255.

Files

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SND_STREAM_BUFFER_MAX

◆ SND_STREAM_INVALID

◆ SND_STREAM_MAX

Typedef Documentation

◆ snd_stream_callback_direct_t

◆ snd_stream_callback_t

◆ snd_stream_filter_t

◆ snd_stream_hnd_t

Function Documentation

◆ snd_stream_alloc()

◆ snd_stream_destroy()

◆ snd_stream_filter_add()

◆ snd_stream_filter_remove()

◆ snd_stream_get_userdata()

◆ snd_stream_init()

◆ snd_stream_init_ex()

◆ snd_stream_pan()

◆ snd_stream_poll()

◆ snd_stream_prefill()

◆ snd_stream_queue_disable()

◆ snd_stream_queue_enable()

◆ snd_stream_queue_go()

◆ snd_stream_reinit()

◆ snd_stream_set_callback()

◆ snd_stream_set_callback_direct()

◆ snd_stream_set_userdata()

◆ snd_stream_shutdown()

◆ snd_stream_start()

◆ snd_stream_start_adpcm()

◆ snd_stream_start_pcm8()

◆ snd_stream_stop()

◆ snd_stream_volume()