Main Page   Compound List   File List   Compound Members   File Members  

cslsample.c File Reference

#include <csl/cslsample.h>
#include <csl/cslmain.h>
#include <csl/cslutils.h>
#include <csl/cslprivate.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <errno.h>
#include <fcntl.h>
#include <unistd.h>

Functions

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

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. 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_play (CslSample *sample)
 Play a sound sample. More...

void csl_sample_release (CslSample *sample)
 Free a sound sample. 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...

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

CslErrorType csl_sample_cache_add (CslSample *sample)
 Add a sound sample to the sample cache. 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...


Detailed Description

The CSL sample API provides a simple means for playing PCM sound samples. You create samples from files or PCM sound data, and send them to the sound server to be played. You can reuse the sample multiple times and share samples with other apps if they are using the same sound server.

Typical usage will follow these steps:

Samples are cached in the sound server as long as they are active (i.e. until released using csl_sample_release). Using csl_sample_cache_add a sample can be permanently added to the sample cache (at least until the server is restarted). Samples can be loaded from the cache using csl_sample_new_from_cache and removed using csl_sample_cache_remove. The caching behaviour may vary depending on which backend is used.


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