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