Main Page   Compound List   File List   Compound Members   File Members  

cslsample.h File Reference

#include <csl/csldefs.h>
#include <csl/cslmain.h>
#include <csl/cslutils.h>

Go to the source code of this file.

Typedefs

typedef _CslSample CslSample
 Sample type. More...


Functions

CslErrorType csl_sample_new (CslDriver *driver, const char *name, const char *role, const char *title, CslSample **sample_p)
 Create a new sample. More...

void csl_sample_release (CslSample *sample)
 Free a sound sample. More...

CslErrorType csl_sample_new_from_file (CslDriver *driver, const char *filename, const char *role, const char *title, CslSample **sample_p)
 Create a sample from a file. More...

CslErrorType csl_sample_new_from_cache (CslDriver *driver, const char *name, const char *role, const char *title, CslSample **sample_p)
 Obtain a sample from the sample cache. More...

int csl_sample_write (CslSample *sample, unsigned int n_bytes, void *bytes)
 Write data into a sample. More...

CslErrorType csl_sample_write_done (CslSample *sample)
 Finish writing data into a sample. More...

CslErrorType csl_sample_cache_add (CslSample *sample)
 Add a sound sample to the sample cache. More...

CslErrorType csl_sample_cache_remove (CslSample *sample)
 Remove a sound sample from the sample cache. More...

CslErrorType csl_sample_play (CslSample *sample)
 Play a sound sample. More...

CslBool csl_sample_is_playing (CslSample *sample)
 Check whether a sample is being played. More...

CslErrorType csl_sample_stop (CslSample *sample)
 Stop playing a sample. More...

CslErrorType csl_sample_wait_done (CslSample *sample)
 Wait until playing a sample is done. More...


Typedef Documentation

typedef struct _CslSample CslSample
 

Sample type.

An opaque type used as a handle to API functions that work with samples.


Function Documentation

CslErrorType csl_sample_cache_add CslSample   sample
 

Add a sound sample to the sample cache.

This adds a sample to the sample cache. It will remain cached even after calling csl_sample_release until csl_sample_cache_remove is called or the sound server is restarted.

Parameters:
sample  A pointer to a previously created CslSample.
Returns:
Error code indicating success or failure.

CslErrorType csl_sample_cache_remove CslSample   sample
 

Remove a sound sample from the sample cache.

This tells the library to remove a sample from the sample cache.

Parameters:
sample  A pointer to a previously created CslSample.

CslBool csl_sample_is_playing CslSample   sample
 

Check whether a sample is being played.

This checks whether a sample is currently being played. If you have started a sample multiple times at once, this will return whether at least one of them is still being played.

Parameters:
sample  A pointer to a previously created CslSample.
Returns:
True if the sample is still playing.

CslErrorType csl_sample_new CslDriver   driver,
const char *    name,
const char *    role,
const char *    title,
CslSample **    sample_p
 

Create a new sample.

This creates a new (empty) sample which can be played back later. In order to use the sample you need to write PCM data into it using csl_sample_write.

Parameters:
driver  A pointer to a previously opened CSL driver.
name  A name for the new sample. You should give a reasonable name with extension (like "bong.wav"), as the implementation might depend on the extension for figuring out the type.
sample_p  A pointer to a pointer to the newly created sample.
Returns:
Error code indicating success or failure.
See also:
csl_sample_new_from_file , csl_sample_write

CslErrorType csl_sample_new_from_cache CslDriver   driver,
const char *    name,
const char *    role,
const char *    title,
CslSample **    sample_p
 

Obtain a sample from the sample cache.

This function attempts to find a sound sample in the sample cache. If found, it returns the sample, otherwise it returns an error status.

Parameters:
driver  A pointer to a previously opened CSL driver.
name  The name for the new sample, which must match the name previously used when the sample was cached.
sample_p  A pointer to a pointer to the cached sample.
Returns:
Error code indicating success or failure.
See also:
csl_sample_new , csl_sample_new_from_file

CslErrorType csl_sample_new_from_file CslDriver   driver,
const char *    name,
const char *    role,
const char *    title,
CslSample **    sample_p
 

Create a sample from a file.

This creates a sample from an existing sound file (e.g. .wav file). It is equivalent to calling csl_sample_new, writing the file contents using csl_sample_write, and then calling csl_sample_write_done.

Parameters:
driver  A pointer to a previously opened CSL driver.
name  A name for the new sample. This should be the name of an existing sound file, with extension (like "bong.wav"). After this call the sample is ready to be played.
sample_p  A pointer to a pointer to the newly created sample.
Returns:
Error code indicating success or failure.
See also:
csl_sample_new , csl_sample_write

CslErrorType csl_sample_play CslSample   sample
 

Play a sound sample.

This plays a sound sample. Note that playing a sample will return immediately. You can use csl_sample_is_playing to check whether it is still playing or csl_sample_wait_done to wait until it is done.

Parameters:
sample  A pointer to a previously created CslSample.
See also:
csl_sample_write
Returns:
Error code indicating success or failure.

void csl_sample_release CslSample   sample
 

Free a sound sample.

This releases the resources associated with a sound sample. You should release a sample when it is no longer required. You must not use the sample after it has been release. A currently playing sample will not be stopped through this function though, use csl_sample_stop if you want that.

Parameters:
sample  A pointer to a previously created CslSample.

CslErrorType csl_sample_stop CslSample   sample
 

Stop playing a sample.

This stops playing a sample (which was started with csl_sample_play) immediately.

Parameters:
sample  A pointer to a previously created CslSample.
Returns:
Error code indicating success or failure.

CslErrorType csl_sample_wait_done CslSample   sample
 

Wait until playing a sample is done.

This waits until playing a sample (which was started with csl_sample_play) is done.

Parameters:
sample  A pointer to a previously created CslSample.
Returns:
Error code indicating success or failure.

int csl_sample_write CslSample   sample,
unsigned int    n_bytes,
void *    bytes
 

Write data into a sample.

This writes PCM data into an empty sample, previously created using csl_sample_new. You can call this function multiple times if desired, and the data will be concatenated together. You indicate that no more data needs to be written by calling csl_sample_write_done. The data format is inferred from the name used when the sample is created with csl_sample_new.

Parameters:
sample  A pointer to a previously created CslSample.
n_bytes  The number of bytes of sample data to be written.
bytes  A pointer to the buffer of PCM data to be written into the sample.
Returns:
The number of bytes written to the sample, normally the same as n_bytes.
See also:
csl_sample_new , csl_sample_write_done

CslErrorType csl_sample_write_done CslSample   sample
 

Finish writing data into a sample.

This is called after one or more calls to csl_sample_write to indicate that you are finished writing data into the sample. The sample is now ready to be played using csl_sample_play.

Parameters:
sample  A pointer to a previously created CslSample.
See also:
csl_sample_write


Generated on Wed Oct 31 18:45:21 2001 for CSL by doxygen1.2.11.1 written by Dimitri van Heesch, © 1997-2001