Main Page Compound List File List Compound Members File Members

# cslpcm.h File Reference

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

Go to the source code of this file.

## Compounds
struct | _CslPcmStatus
| PCM stream status type. More...
## Defines
#define | CSL_PCM_FORMAT_S16_HE CSL_PCM_FORMAT_S16_LE
#define | CSL_PCM_FORMAT_FLOAT_HE CSL_PCM_FORMAT_FLOAT_LE
#define | CSL_PCM_CHANNEL_FRONT_LEFT "<front-left>"
#define | CSL_PCM_CHANNEL_FRONT_RIGHT "<front-right>"
#define | CSL_PCM_CHANNEL_CENTER "<center>"
#define | CSL_PCM_CHANNEL_REAR_LEFT "<rear-left>"
#define | CSL_PCM_CHANNEL_REAR_RIGHT "<rear-right>"
#define | CSL_PCM_CHANNEL_SUB_WOOFER "<sub-woofer>"
## Typedefs
typedef _CslPcmStream | CslPcmStream
| PCM stream type. More...
typedef _CslPcmStatus | CslPcmStatus
| PCM stream status type. More...
## Enumerations
enum | CslPcmFormatType { CSL_PCM_FORMAT_SIZE_8 = 0x0008, CSL_PCM_FORMAT_SIZE_16 = 0x0010, CSL_PCM_FORMAT_SIZE_32 = 0x0020, CSL_PCM_FORMAT_SIZE_MASK = 0x00FF, CSL_PCM_FORMAT_ENDIAN_LE = 0x0100, CSL_PCM_FORMAT_ENDIAN_BE = 0x0200, CSL_PCM_FORMAT_ENDIAN_MASK = 0x0F00, CSL_PCM_FORMAT_ENCODING_LINEAR_SIGNED = 0x1000, CSL_PCM_FORMAT_ENCODING_LINEAR_UNSIGNED = 0x2000, CSL_PCM_FORMAT_ENCODING_FLOAT = 0x3000, CSL_PCM_FORMAT_ENCODING_MASK = 0xF000, CSL_PCM_FORMAT_U8 = 0x2008, CSL_PCM_FORMAT_S16_LE = 0x1110, CSL_PCM_FORMAT_S16_BE = 0x1210, CSL_PCM_FORMAT_FLOAT_LE = 0x3120, CSL_PCM_FORMAT_FLOAT_BE = 0x3220 }
| PCM data format type. More...
## Functions
CslErrorType | csl_pcm_open_output (CslDriver *driver, const char *role, unsigned int rate, unsigned int n_channels, CslPcmFormatType format, CslPcmStream **stream_p)
| Open PCM input stream. More...
CslErrorType | csl_pcm_open_input (CslDriver *driver, const char *role, unsigned int rate, unsigned int n_channels, CslPcmFormatType format, CslPcmStream **stream_p)
| Open PCM output stream. More...
CslPcmFormatType | csl_pcm_get_format (CslPcmStream *stream)
| Return stream format. More...
void | csl_pcm_close (CslPcmStream *stream)
| Close PCM stream. More...
int | csl_pcm_read (CslPcmStream *stream, unsigned int n_bytes, void *bytes)
| Read from a stream. More...
int | csl_pcm_write (CslPcmStream *stream, unsigned int n_bytes, void *bytes)
| Write to a stream. More...
CslErrorType | csl_pcm_get_status (CslPcmStream *stream, CslPcmStatus *status)
| Get stream status. More...
CslErrorType | csl_pcm_flush (CslPcmStream *stream)
| Flush PCM data. More...
CslErrorType | csl_pcm_sync (CslPcmStream *stream)
| Sync PCM data. More...
CslErrorType | csl_pcm_set_title (CslPcmStream *stream, const char *title)
| Set stream title. More...
char * | csl_pcm_dup_title (CslPcmStream *stream)
| Get stream title. More...
CslErrorType | csl_pcm_set_stream_mode (CslPcmStream *stream, unsigned int buffer_size, unsigned int byte_watermark)
| Put PCM stream to streaming mode, set buffer settings. More...
void | csl_pcm_get_stream_settings (CslPcmStream *stream, unsigned int *buffer_size_p, unsigned int *byte_watermark_p)
| Get PCM stream settings. More...
CslErrorType | csl_pcm_set_packet_mode (CslPcmStream *stream, unsigned int n_packets, unsigned int packet_size, unsigned int packet_watermark)
| Put PCM stream to packet mode, set buffer settings. More...
void | csl_pcm_get_packet_settings (CslPcmStream *stream, unsigned int *n_packets_p, unsigned int *packet_size_p, unsigned int *packet_watermark_p)
| Get PCM stream packet settings. More...

## Detailed Description

This file defines the CSL API functions related to PCM data.

## Define Documentation

#define CSL_PCM_CHANNEL_CENTER "<center>"

#define CSL_PCM_CHANNEL_FRONT_LEFT "<front-left>"

#define CSL_PCM_CHANNEL_FRONT_RIGHT "<front-right>"

#define CSL_PCM_CHANNEL_REAR_LEFT "<rear-left>"

#define CSL_PCM_CHANNEL_REAR_RIGHT "<rear-right>"

#define CSL_PCM_CHANNEL_SUB_WOOFER "<sub-woofer>"

#define CSL_PCM_FORMAT_FLOAT_HE CSL_PCM_FORMAT_FLOAT_LE

#define CSL_PCM_FORMAT_S16_HE CSL_PCM_FORMAT_S16_LE

## Typedef Documentation

typedef struct _CslPcmStatus CslPcmStatus

| PCM stream status type. A type used to store status information related to PCM streams.

typedef struct _CslPcmStream CslPcmStream

| PCM stream type. An opaque type used as a handle to API functions that work with PCM streams.

## Enumeration Type Documentation

enum CslPcmFormatType

  | PCM data format type. Data type for specifying PCM format. See also: csl_pcm_open_output , csl_pcm_open_input , csl_pcm_get_format Enumeration values:
  CSL_PCM_FORMAT_SIZE_8 | size (obligatory)
  CSL_PCM_FORMAT_SIZE_16 |
  CSL_PCM_FORMAT_SIZE_32 |
  CSL_PCM_FORMAT_SIZE_MASK |
  CSL_PCM_FORMAT_ENDIAN_LE | endianess (obligatory for size > 8)
  CSL_PCM_FORMAT_ENDIAN_BE |
  CSL_PCM_FORMAT_ENDIAN_MASK |
  CSL_PCM_FORMAT_ENCODING_LINEAR_SIGNED | encoding (obligatory)
  CSL_PCM_FORMAT_ENCODING_LINEAR_UNSIGNED |
  CSL_PCM_FORMAT_ENCODING_FLOAT |
  CSL_PCM_FORMAT_ENCODING_MASK |
  CSL_PCM_FORMAT_U8 | aliases
  CSL_PCM_FORMAT_S16_LE |
  CSL_PCM_FORMAT_S16_BE |
  CSL_PCM_FORMAT_FLOAT_LE |
  CSL_PCM_FORMAT_FLOAT_BE |

## Function Documentation

void csl_pcm_close | ( | CslPcmStream * | stream | ) |

  | Close PCM stream. Close a PCM input or output stream. Parameters:
  stream | The stream to be closed.
See also: csl_pcm_open_output , csl_pcm_open_input

char* csl_pcm_dup_title | ( | CslPcmStream * | stream | ) |

  | Get stream title. Return the title string associated with a stream. Parameters:
  stream | The PCM stream.
Returns: The stream name. This is a dynamically allocated string which needs to be freed using csl_free when no longer needed. See also: csl_pcm_set_title

CslErrorType csl_pcm_flush | ( | CslPcmStream * | stream | ) |

  | Flush PCM data. Cancel any pending output written to an output stream. After a call to csl_pcm_write, data may still be stored in buffers. Calling this function will remove as many of these bytes as possible, i.e. try to stop playing immediately, cancelling already written bytes. Warning: Not yet implemented by all backend drivers. Parameters:
  stream | The PCM stream to flush.
Returns: Error status code.

CslPcmFormatType csl_pcm_get_format | ( | CslPcmStream * | stream | ) |

  | Return stream format. Return format information about a PCM stream. Parameters:
  stream | A previously opened stream.
Returns: The stream format information.

void csl_pcm_get_packet_settings | ( | CslPcmStream * | stream,
|  | unsigned int * | n_packets_p,
|  | unsigned int * | packet_size_p,
|  | unsigned int * | packet_watermark_p
| ) |

  | Get PCM stream packet settings. Get the current stream settings for number of packets, size, and watermark. Parameters:
  stream | The PCM stream.
  n_packets_p | Pointer to variable to store number of packets.
  packet_size_p | Pointer to variable to store packet size, in bytes.
  packet_watermark_p | Pointer to variable to store watermark setting.
Returns: Error status code

CslErrorType csl_pcm_get_status | ( | CslPcmStream * | stream,
|  | CslPcmStatus * | status
| ) |

  | Get stream status. Obtains status information about a PCM stream. Parameters:
  stream | The PCM stream to query.
  status | A pointer to variable to write the status information.
Returns: Error status code.

void csl_pcm_get_stream_settings | ( | CslPcmStream * | stream,
|  | unsigned int * | buffer_size_p,
|  | unsigned int * | byte_watermark_p
| ) |

  | Get PCM stream settings. Get the current stream settings for buffer size and watermark. Parameters:
  stream | The PCM stream.
  buffer_size_p | Pointer to variable to store returned buffer size.
  byte_watermark_p | Pointer to variable to store watermark setting.
Returns: Error status code

CslErrorType csl_pcm_open_input | ( | CslDriver * | driver,
|  | const char * | role,
|  | unsigned int | rate,
|  | unsigned int | n_channels,
|  | CslPcmFormatType | format,
|  | CslPcmStream ** | stream_p
| ) |

  | Open PCM output stream. Open a PCM stream for input, specifying a driver and data format. Parameters:
  driver | A pointer to a previously opened CSL driver.
  role | A, identifier string that can be used by the underlying driver (see description under csl_pcm_open_output).
  rate | Sampling rate in samples/second.
  n_channels | Number of channels.
  format | PCM data format.
  stream_p | A pointer to write the opened stream.
Returns: Error code indicating success or failure. See also: csl_pcm_open_input , csl_pcm_close

CslErrorType csl_pcm_open_output | ( | CslDriver * | driver,
|  | const char * | role,
|  | unsigned int | rate,
|  | unsigned int | n_channels,
|  | CslPcmFormatType | format,
|  | CslPcmStream ** | stream_p
| ) |

  | Open PCM input stream. Open a PCM stream for output, specifying a driver and data format. Parameters:
  driver | A pointer to a previously opened CSL driver.
  role | A, identifier string used by the underlying driver. The role must be constant for a stream, should not be internationalized, and should should be different for different kinds of streams For eexample, role coul be assigned to something like "quake", "noatun", or "quake-sounds". This argument is mandatory.
  rate | Sampling rate in samples/second.
  n_channels | Number of channels.
  format | PCM data format.
  stream_p | A pointer to write the opened stream.
Returns: Error code indicating success or failure. See also: csl_pcm_open_input , csl_pcm_close

int csl_pcm_read | ( | CslPcmStream * | stream,
|  | unsigned int | n_bytes,
|  | void * | bytes
| ) |

  | Read from a stream. Read bytes from a PCM input stream. Parameters:
  stream | The PCM stream to read.
  n_bytes | Number of bytes to read.
  bytes | Pointer to buffer to store the data read.
Returns: Returns the number of bytes read or -1 if an error occurred. See also: csl_pcm_write

CslErrorType csl_pcm_set_packet_mode | ( | CslPcmStream * | stream,
|  | unsigned int | n_packets,
|  | unsigned int | packet_size,
|  | unsigned int | packet_watermark
| ) |

  | Put PCM stream to packet mode, set buffer settings. Put the CslPcmStream into packet mode, or, if already in packet mode, alter the buffer and watermark settings. For writable streams, the watermark indicates the amount of packets that should be writable before csl_select() flags this stream as writable. For readable streams, this means the amount of packets that should be readable before csl_select() flags this stream as readable. The resulting values strongly depend on the driver implementation and should be queried after invoking this function with csl_pcm_get_packet_settings(). Parameters:
  n_packets | Number of packets to be kept in buffer
  packet_size | Size of a packet in bytes
  packet_watermark | The fill state watermark in number of packets
Returns: Whether setting packet mode parameters succeeded.

CslErrorType csl_pcm_set_stream_mode | ( | CslPcmStream * | stream,
|  | unsigned int | buffer_size,
|  | unsigned int | byte_watermark
| ) |

  | Put PCM stream to streaming mode, set buffer settings. Put the CslPcmStream into streaming mode, or, if already in streaming mode, alter the buffer and watermark settings. For writable streams, the watermark indicates the amount of bytes that should be writable before csl_select() flags this stream as writable. For readable streams, this means the amount of bytes that should be readable before csl_select() flags this stream as readable. The resulting values strongly depend on the driver implementation and should be queried after invoking this function with csl_pcm_get_stream_settings(). Parameters:
  stream | The PCM stream to change
  buffer_size | The buffer size in bytes for streaming mode
  byte_watermark | The fill state watermark into buffer
Returns: Whether setting stream parameters succeeded.

CslErrorType csl_pcm_set_title | ( | CslPcmStream * | stream,
|  | const char * | title
| ) |

  | Set stream title. Associate a title string with the stream. The title may be shown to the end user to describe the stream. The title should be internationalized (in UTF-8 format) and can change. If you don't assign a title, it will default to the role parameter for the stream. Parameters:
  title | String to use as the title.
  stream | The PCM stream.
Returns: Error status code See also: csl_pcm_dup_title

CslErrorType csl_pcm_sync | ( | CslPcmStream * | stream | ) |

  | Sync PCM data. Ensure PCM data has been written to an output device. After a call to csl_pcm_write, data may still be stored in buffers. Calling this function ensures that it has actually been written to the audio output device. Warning: Not yet implemented by backend drivers. Parameters:
  stream | The PCM stream to sync.
Returns: Error status code.

int csl_pcm_write | ( | CslPcmStream * | stream,
|  | unsigned int | n_bytes,
|  | void * | bytes
| ) |

  | Write to a stream. Write bytes to a PCM output stream. Parameters:
  stream | The PCM stream to write.
  n_bytes | Number of bytes to write.
  bytes | Pointer to buffer containing the data to be written.
Returns: Returns the number of bytes written or -1 if an error occurred. See also: csl_pcm_read