Simple Sound for Small Devices
libsssd
last updated: 14 JUN 2003 (v0.6)
Function Name:  sssd_ctrlSample

   Allows program to control attributes of currently playing samples.  Arguments are passed in an int array as token-parameter pairs.

C Prototype:

int sssd_ctrlSample( struct sssdaudio* ga, int sample_id, int *parameters);

  Other Prototypes:


Arguments:

struct gameaudio *ga

    Pointer to an initialized sssdaudio structure (returned by sssd_initAudio)

int sample_id

    Sample_id number returned from loadSample..., copySample..., or registerSample, OR playing_id returned from a playSample call.

int *parameters (tag pair list)

    Parameters are a list of tag-parameters pairs, terminated with CTRL_S_END.  All values for ctrlSample parameters are the same as used when playing a sample (usually int)   Currently, supported parameters are:

CTRL_S_VOLUME
    Sets a playing sample's volume (0 - 256)

CTRL_S_PAN
    Set's a playing sample's stereo pan. (-128 - 128)

CTRL_S_PLAYEND
    Sample playing should stop at sample number

CTRL_S_LOOPSTART
    Sample looping begins at sample number

CTRL_S_LOOPEND
    Sample looping starts back at loopStart

CTRL_S_PRIORITY
    Priority of playing sample (currently unsupported)

CTRL_S_LOOPCOUNT
    Number of times to loop the sample, or 0 for indefinate.

CTRL_S_ARRAY
    The parameter is a pointer to an int array containting token-parameter pairs.  Note this must be the first and only token.


Returns:

0
    Success

ERR_SAMPLES_RANGE
    The provided sample or playing ID is out of range.

ERR_SAMPLES_ATTRIB
    A parameter supplied to ctrlSample was unknown.  ctrlSample() continues to process tag pair skipping those not recognized.

Example:

int sample_id;
int playing_id1, playing_id2;
sssdaudio *ga;
int parmArray[9];


/* init and setup */
...
/* Load Sample */
sample_id=sssd_loadSample(ga,"someSoundFile.wav");

/*  Play Sample - looping forever */
playing_id1=sssd_playSample(ga, sample_id,
                            0,    /* Loop Forever */
                            256,  /* Full Volume */
                            0);   /* center pan */

playing_id2=sssd_playSample(ga, sample_id,
                            0,    /* Loop Forever */
                            256,  /* Full Volume */
                            0);   /* center pan */

        
/* Set volume of ALL playing instances of 'sample_id' to 128 */
parmArray[0]=CTRL_S_VOLUME; /* tag */
parmArray[1]=128;           /* parameter value */
parmArray[2]=CTRL_S_END;    /* end */
ctrlSample(ga, sample_id, parmArray);

/* Pan one playing instance of sample_id to the left, the other to the right */
parmArray[0]=CTRL_S_PAN; /* tag */
parmArray[1]=-128;           /* parameter value */
parmArray[2]=CTRL_S_END;    /* end */
ctrlSample(ga, playing_id1, parmArray);

parmArray[1]=128;           /* parameter value */
ctrlSample(ga, playing_id2, parmArray);

/* Reset all playing instances of 'sample_id' to full volume, center pan */
parmArray[0]=CTRL_S_VOLUME;
parmArray[0]=256;
parmArray[0]=CTRL_S_PAN;
parmArray[0]=0;
parmArray[0]=CTRL_S_END;
ctrlSample(ga, sample_id, parmArray);

/* rest of program */
...

libsssd (c)2003 Patrick Roberts created from libgaudio (c) 1999-2000 A. Schiffler.  Release as open source under MPL 1.1.  Documentation (c)2003 Patrick Roberts.