source: downloads/openal-0.0.8/src/al_source.h @ 24

/* -*- mode: C; tab-width:8; c-basic-offset:8 -*-
 * vi:set ts=8:
 *
 * al_source.h
 *
 * Prototypes, macros and definitions related to the creation and
 * management of sources.
 *
 */
#ifndef _AL_SOURCE_H_
#define _AL_SOURCE_H_

#include <stdio.h>

#include "al_types.h"

/*
 * Non locking version of alIsSource.
 */
ALboolean _alIsSource( ALuint sid );

/*
 * Returns AL_source named by sid from context named by cid.
 */
AL_source *_alGetSource( ALuint cid, ALuint sid );

/*
 * Returns a pointer to the attribute specified by param in the AL_source
 * object *source, or NULL if the attribute is invalid or has not been set.
 */
void *_alGetSourceParam( AL_source *source, ALenum param );

/*
 * Returns AL_TRUE if param is a valid source attribute and has been set in
 * source, AL_FALSE otherwise.
 */
ALboolean _alSourceIsParamSet( AL_source *source, ALenum param );

/*
 * Populates *retref with the default value for source attribute param.  If
 * param is not a valid source attribute, no action is taken.
 */
void _alSourceGetParamDefault( ALenum param, ALvoid *retref );

/*
 * Finalize a source object.
 */
void _alDestroySource( ALvoid *src );

/*
 * Finalize each source object referenced in spool ( see al_spool.h for more
 * information about source pool objects and their relationship to AL_sources).
 */
void _alDestroySources( spool_t *spool );

/*
 * Populate buffs[0..nc-1][0..len/2-1] with data from buf, with offset into
 * buf given by the position associated with the source named by sid in the
 * context named by cid.
 *
 * This function delegates to static functions in the case of looping or
 * callback sounds.
 */
void _alSplitSources( ALuint cid, ALuint sid,
                      ALint nc, ALuint len,
                      AL_buffer *buf, ALshort **buffs );

/*
 * Populates the scratch space associated with the source named by sid in the
 * context named by cid with interleaved data.  The data is interleaved using
 * alternating channels from buffers[0..nc-1].  Each member of the set
 * buffers[0..nc-1] is an indepedent channel's worth of data, 0..mixbuflen/2
 * long bytes long.
 */
void _alCollapseSource( ALuint cid, ALuint sid,
                        ALuint nc, ALuint mixbuflen,
                        ALshort **buffers );


/*
 * Translates the source (src) position attribute by delta.  Delta is a three
 * tuple x/y/z.
 */
void _alSourceTranslate( AL_source *src, ALfloat *delta );

/*
 * srcParam functions
 *
 * The use of srcParam settings is this: most filter operations break down
 * into applying a multiplier or delay to the raw PCM data copied in
 * SplitSources.  Since there operations are cumulative, this can be simplified
 * by simply collecting the coefficients of the operations and applying them
 * all at one.  So instead of actually performing a gain or delay operation on
 * the PCM data, the filter can change the srcParam setting, which is applied
 * in _alSourceParamApply.
 *
 */

/*
 * Resets the srcParam settings gain and delay.  Does not affect srcParam
 * settings associated with sound position or the temporary scratch space.
 */
void _alSourceParamReset( AL_source *src );

/*
 * Applies the srcParam settings of src to buffers[0..nc-1][0..(len/2)-1].
 */
void _alSourceParamApply( AL_source *src,
                          ALuint nc, ALuint len, ALshort **buffers );

/*
 * Returns the number of buffers queued in the source, not including the
 * current one ( if any ).
 */
ALint _alSourceGetPendingBids( AL_source *src );

/*
 * Returns the next buffer in a queue, or NULL if no next buffer exists.
 * Assumes locked source.
 *
 */
AL_buffer *_alSourceGetNextBuffer( AL_source *src );

/*
 * Returns the total number of buffers queued for the source,
 * without regard to the read or write pointer.
 */
ALint _alSourceQueuedBuffers( AL_source *src );

/*
 * Copies the interleaved data from src[0..(src_size/2)-1] to
 * dstret[0..dest_channels-1], splitting it into seperate channels.
 * src_channels describes the period of the channel repetition in src,
 * dest_channels describes the number of independant buffers in dstref.
 * src_size is the size of src in bytes, and offset is the offset into each
 * seperate channel in dstref where the copying begins.
 */
void _alMonoifyOffset( ALshort **dstref, ALuint offset,
                       ALvoid *src, ALuint src_size,
                       ALuint dest_channels, ALuint src_channels );

/*
 * This function is sort of the complement of _alMonoifyOffset.  Data is
 * copied from srcs[0..nc-1][offset/2..(offset + size)/2-1] into an
 * interleaved array dst.
 */
void _alChannelifyOffset( ALshort *dst, ALuint offset,
                          ALshort **srcs, ALuint size, ALuint nc );


/*
 * Usually, the top-level mixing function _alMixSources handles updating each
 * source's sound position ( a pointer into its associate buffer's raw PCM
 * data. )  Some attributes, like pitch, demand a more sophisticated approach
 * that can only be done by the filter which handles this attribute.
 *
 * _alSourceShouldIncrement returns AL_TRUE if the top-level mixing function
 * should update this sort of state information, and AL_FALSE if it should
 * leave it to another portion of the library.
 */
ALboolean _alSourceShouldIncrement( AL_source *src );

/*
 * Increments the source's (src) offset into its current buffer's PCM data.
 */
void _alSourceIncrement( AL_source *src, ALuint bytes );

/*
 * Returns the byte length of the amount of data left before this source/samp
 * pair will either run out of data or be required to wrap.  This returns the
 * byte length of an interleaved array, with periodic repetition equal to the
 * number of channels in the canonical format.
 */
ALint _alSourceBytesLeft( AL_source *src, AL_buffer *samp );

/*
 * Returns the byte length of the amount of data left before this source/samp
 * pair will either run out of data or be required to wrap.  This returns the
 * byte length of a simple array, with 1 channel's worth of data.
 */
ALint _alSourceBytesLeftByChannel( AL_source *src, AL_buffer *samp );

/*
 * Returns AL_TRUE if the source (src) has its queue set to AL_TRUE,
 * AL_FALSE otherwise.
 */
ALboolean _alSourceIsQueue( AL_source * src );

/*
 * Returns AL_TRUE if the source (src) has its AL_LOOPING attribute set to
 * AL_TRUE, AL_FALSE otherwise.
 */
ALboolean _alSourceIsLooping( AL_source *src );

/*
 * Locks the mutex guarding source sid in context cid, and passes fn and ln
 * to _alLockPrintf for debugging purposes.
 */
ALboolean FL_alLockSource( const char *fn, int ln, ALuint cid, ALuint sid );

/*
 * Unlocks the mutex guarding source sid in context cid, and passes fn and ln
 * to _alLockPrintf for debugging purposes.
 */
ALboolean FL_alUnlockSource( const char *fn, int ln, ALuint cid, ALuint sid );

/* macros */
#define _alDCGetSource(i)              _alGetSource(_alcCCId, i)
#define _alChannelify(d,srcs,size,nc)  _alChannelifyOffset(d, 0, srcs, size, nc)
#define _alMonoify(d, s, size, dc, sc) _alMonoifyOffset(d, 0, s, size, dc, sc)
#define _alLockSource(cid, sid)        FL_alLockSource(__FILE__, __LINE__, cid, sid)
#define _alUnlockSource(cid, sid)      FL_alUnlockSource(__FILE__, __LINE__, cid, sid)
#define _alDCLockSource(sid)           FL_alLockSource(__FILE__, __LINE__, _alcCCId, sid)
#define _alDCUnlockSource(sid)         FL_alUnlockSource(__FILE__, __LINE__, _alcCCId, sid)

#ifdef PARANOID_LOCKING
#define SOURCELOCK()   _alcDCLockContext()
#define SOURCEUNLOCK() _alcDCUnlockContext()
#else
#define SOURCELOCK()
#define SOURCEUNLOCK()
#endif

/*
 * AL_FIRST_SOURCE_ID is the first integer value at which source names are
 * created.
 */
#define AL_FIRST_SOURCE_ID  0x4000

#endif /* _AL_SOURCE_H_ */