ALSA project - the C library reference

Loading...
Searching...
No Matches
Macros | Functions
Hardware Parameters
PCM Interface

## Macros
#define | snd_pcm_hw_params_alloca(ptr)
| allocate an invalid snd_pcm_hw_params_t using standard alloca

## Functions
int | snd_pcm_hw_params_any (snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
| Fill params with a full configuration space for a PCM.
int | snd_pcm_hw_params_can_mmap_sample_resolution (const snd_pcm_hw_params_t *params)
| Check if hardware supports sample-resolution mmap for given configuration.
int | snd_pcm_hw_params_is_double (const snd_pcm_hw_params_t *params)
| Check if hardware does double buffering for start/stop for given configuration.
int | snd_pcm_hw_params_is_batch (const snd_pcm_hw_params_t *params)
| Check if hardware does double buffering for data transfers for given configuration.
int | snd_pcm_hw_params_is_block_transfer (const snd_pcm_hw_params_t *params)
| Check if hardware does block transfers for samples for given configuration.
int | snd_pcm_hw_params_is_monotonic (const snd_pcm_hw_params_t *params)
| Check if timestamps are monotonic for given configuration.
int | snd_pcm_hw_params_can_overrange (const snd_pcm_hw_params_t *params)
| Check if hardware supports overrange detection.
int | snd_pcm_hw_params_can_pause (const snd_pcm_hw_params_t *params)
| Check if hardware supports pause.
int | snd_pcm_hw_params_can_resume (const snd_pcm_hw_params_t *params)
| Check if hardware supports resume.
int | snd_pcm_hw_params_is_half_duplex (const snd_pcm_hw_params_t *params)
| Check if hardware does half-duplex only.
int | snd_pcm_hw_params_is_joint_duplex (const snd_pcm_hw_params_t *params)
| Check if hardware does joint-duplex (playback and capture are somewhat correlated)
int | snd_pcm_hw_params_can_sync_start (const snd_pcm_hw_params_t *params)
| Check if hardware supports synchronized start with sample resolution.
int | snd_pcm_hw_params_can_disable_period_wakeup (const snd_pcm_hw_params_t *params)
| Check if hardware can disable period wakeups.
int | snd_pcm_hw_params_is_perfect_drain (const snd_pcm_hw_params_t *params)
| Check if hardware is capable of perfect drain.
int | snd_pcm_hw_params_supports_audio_wallclock_ts (const snd_pcm_hw_params_t *params)
| Check if hardware supports audio wallclock timestamps.
int | snd_pcm_hw_params_supports_audio_ts_type (const snd_pcm_hw_params_t *params, int type)
| Check if hardware supports type of audio timestamps.
int | snd_pcm_hw_params_get_rate_numden (const snd_pcm_hw_params_t *params, unsigned int *rate_num, unsigned int *rate_den)
| Get rate exact info from a configuration space.
int | snd_pcm_hw_params_get_sbits (const snd_pcm_hw_params_t *params)
| Get sample resolution info from a configuration space.
int | snd_pcm_hw_params_get_fifo_size (const snd_pcm_hw_params_t *params)
| Get hardware FIFO size info from a configuration space.
const unsigned char * | snd_pcm_hw_params_get_sync (const snd_pcm_hw_params_t *params)
| Get hardware synchronization ID from a PCM info container.
size_t | snd_pcm_hw_params_sizeof (void)
| get size of snd_pcm_hw_params_t
int | snd_pcm_hw_params_malloc (snd_pcm_hw_params_t **ptr)
| allocate an invalid snd_pcm_hw_params_t using standard malloc
void | snd_pcm_hw_params_free (snd_pcm_hw_params_t *obj)
| frees a previously allocated snd_pcm_hw_params_t
void | snd_pcm_hw_params_copy (snd_pcm_hw_params_t *dst, const snd_pcm_hw_params_t *src)
| copy one snd_pcm_hw_params_t to another
int | snd_pcm_hw_params_get_min_align (const snd_pcm_hw_params_t *params, snd_pcm_uframes_t *val)
| Get the minimum transfer align value in samples.

## Detailed Description

See the PCM (digital audio) interface page for more details.

## Macro Definition Documentation

## ◆ snd_pcm_hw_params_alloca

#define snd_pcm_hw_params_alloca | ( |  | ptr | ) |

allocate an invalid snd_pcm_hw_params_t using standard alloca

Parameters

  ptr | returned pointer

Examples
  /test/latency.c, and /test/pcm.c.

## Function Documentation

## ◆ snd_pcm_hw_params_any()

int snd_pcm_hw_params_any | ( | snd_pcm_t * | pcm,
|  | snd_pcm_hw_params_t * | params )

Fill params with a full configuration space for a PCM.

Parameters

  pcm | PCM handle
  params | Configuration space

The configuration space will be filled with all possible ranges for the PCM device.

Note that the configuration space may be constrained by the currently installed configuration on the PCM device. To remove any constrains, free the configuration with snd_pcm_hw_free first.

Examples
  /test/latency.c, and /test/pcm.c.

## ◆ snd_pcm_hw_params_can_disable_period_wakeup()

int snd_pcm_hw_params_can_disable_period_wakeup | ( | const snd_pcm_hw_params_t * | params | ) |

Check if hardware can disable period wakeups.

Parameters

  params | Configuration space

Return values

  0 | Hardware cannot disable period wakeups
  1 | Hardware can disable period wakeups

Examples
  /test/latency.c.

## ◆ snd_pcm_hw_params_can_mmap_sample_resolution()

int snd_pcm_hw_params_can_mmap_sample_resolution | ( | const snd_pcm_hw_params_t * | params | ) |

Check if hardware supports sample-resolution mmap for given configuration.

Parameters

  params | Configuration space

Return values

  0 | Hardware doesn't support sample-resolution mmap
  1 | Hardware supports sample-resolution mmap

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.

## ◆ snd_pcm_hw_params_can_overrange()

int snd_pcm_hw_params_can_overrange | ( | const snd_pcm_hw_params_t * | params | ) |

Check if hardware supports overrange detection.

Parameters

  params | Configuration space

Return values

  0 | Hardware doesn't support overrange detection
  1 | Hardware supports overrange detection

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.

## ◆ snd_pcm_hw_params_can_pause()

int snd_pcm_hw_params_can_pause | ( | const snd_pcm_hw_params_t * | params | ) |

Check if hardware supports pause.

Parameters

  params | Configuration space

Return values

  0 | Hardware doesn't support pause
  1 | Hardware supports pause

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.

## ◆ snd_pcm_hw_params_can_resume()

int snd_pcm_hw_params_can_resume | ( | const snd_pcm_hw_params_t * | params | ) |

Check if hardware supports resume.

Parameters

  params | Configuration space

Return values

  0 | Hardware doesn't support resume
  1 | Hardware supports resume

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.

## ◆ snd_pcm_hw_params_can_sync_start()

int snd_pcm_hw_params_can_sync_start | ( | const snd_pcm_hw_params_t * | params | ) |

Check if hardware supports synchronized start with sample resolution.

Parameters

  params | Configuration space

Return values

  0 | Hardware doesn't support synchronized start
  1 | Hardware supports synchronized start

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.

## ◆ snd_pcm_hw_params_copy()

void snd_pcm_hw_params_copy | ( | snd_pcm_hw_params_t * | dst,
|  | const snd_pcm_hw_params_t * | src )

copy one snd_pcm_hw_params_t to another

Parameters

  dst | pointer to destination
  src | pointer to source

Examples
  /test/latency.c.

## ◆ snd_pcm_hw_params_free()

void snd_pcm_hw_params_free | ( | snd_pcm_hw_params_t * | obj | ) |

frees a previously allocated snd_pcm_hw_params_t

Parameters

  obj | pointer to object to free

## ◆ snd_pcm_hw_params_get_fifo_size()

int snd_pcm_hw_params_get_fifo_size | ( | const snd_pcm_hw_params_t * | params | ) |

Get hardware FIFO size info from a configuration space.

Parameters

  params | Configuration space

Returns
  FIFO size in frames otherwise a negative error code if the info is not available

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.

## ◆ snd_pcm_hw_params_get_min_align()

int snd_pcm_hw_params_get_min_align | ( | const snd_pcm_hw_params_t * | params,
|  | snd_pcm_uframes_t * | val )

Get the minimum transfer align value in samples.

Parameters

  params | Configuration space
  val | Returned minimum align value

Returns
  0 otherwise a negative error code if the configuration space does not contain a single value

## ◆ snd_pcm_hw_params_get_rate_numden()

int snd_pcm_hw_params_get_rate_numden | ( | const snd_pcm_hw_params_t * | params,
|  | unsigned int * | rate_num,
|  | unsigned int * | rate_den )

Get rate exact info from a configuration space.

Parameters

  params | Configuration space
  rate_num | Pointer to returned rate numerator
  rate_den | Pointer to returned rate denominator

Returns
  0 otherwise a negative error code if the info is not available

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.

## ◆ snd_pcm_hw_params_get_sbits()

int snd_pcm_hw_params_get_sbits | ( | const snd_pcm_hw_params_t * | params | ) |

Get sample resolution info from a configuration space.

Parameters

  params | Configuration space

Returns
  sample resolution (in bits) otherwise a negative error code if the info is not available

For linear formats, this function returns sample resolution - used bits starting from the first usable significant bit defined by the format (e.g. bit 31 for S32_LE format or bit 23 for S24_LE format - starting from bit zero). Application may use full sample bit range defined by the format, but additional bits (outside this sample resolution) are stripped (not processed).

For non-linear formats, this value may have a special meaning which may be defined in future.

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.

## ◆ snd_pcm_hw_params_get_sync()

const unsigned char * snd_pcm_hw_params_get_sync | ( | const snd_pcm_hw_params_t * | params | ) |

Get hardware synchronization ID from a PCM info container.

Parameters

  params | Configuration space

Returns
  16-byte synchronization ID (use SND_PCM_HW_PARAMS_SYNC_SIZE)

This synchronization ID determines the similar clocks for the PCM stream between multiple devices (including different cards). "All zeros" means "not set". The contents of the ID can be used only for a comparison with the contents of another ID returned from this function. Applications should not do a comparison with hard-coded values, because the implementation generating such synchronization IDs may be changed in future.

## ◆ snd_pcm_hw_params_is_batch()

int snd_pcm_hw_params_is_batch | ( | const snd_pcm_hw_params_t * | params | ) |

Check if hardware does double buffering for data transfers for given configuration.

Parameters

  params | Configuration space

Return values

  0 | Hardware doesn't do double buffering for data transfers
  1 | Hardware does double buffering for data transfers

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.

## ◆ snd_pcm_hw_params_is_block_transfer()

int snd_pcm_hw_params_is_block_transfer | ( | const snd_pcm_hw_params_t * | params | ) |

Check if hardware does block transfers for samples for given configuration.

Parameters

  params | Configuration space

Return values

  0 | Hardware doesn't block transfers
  1 | Hardware does block transfers

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.

## ◆ snd_pcm_hw_params_is_double()

int snd_pcm_hw_params_is_double | ( | const snd_pcm_hw_params_t * | params | ) |

Check if hardware does double buffering for start/stop for given configuration.

Parameters

  params | Configuration space

Return values

  0 | Hardware doesn't do double buffering for start/stop
  1 | Hardware does double buffering for start/stop

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.

## ◆ snd_pcm_hw_params_is_half_duplex()

int snd_pcm_hw_params_is_half_duplex | ( | const snd_pcm_hw_params_t * | params | ) |

Check if hardware does half-duplex only.

Parameters

  params | Configuration space

Return values

  0 | Hardware doesn't do half-duplex
  1 | Hardware does half-duplex

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.

## ◆ snd_pcm_hw_params_is_joint_duplex()

int snd_pcm_hw_params_is_joint_duplex | ( | const snd_pcm_hw_params_t * | params | ) |

Check if hardware does joint-duplex (playback and capture are somewhat correlated)

Parameters

  params | Configuration space

Return values

  0 | Hardware doesn't do joint-duplex
  1 | Hardware does joint-duplex

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.

## ◆ snd_pcm_hw_params_is_monotonic()

int snd_pcm_hw_params_is_monotonic | ( | const snd_pcm_hw_params_t * | params | ) |

Check if timestamps are monotonic for given configuration.

Parameters

  params | Configuration space

Return values

  0 | Device doesn't do monotomic timestamps
  1 | Device does monotonic timestamps

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.

## ◆ snd_pcm_hw_params_is_perfect_drain()

int snd_pcm_hw_params_is_perfect_drain | ( | const snd_pcm_hw_params_t * | params | ) |

Check if hardware is capable of perfect drain.

Parameters

  params | Configuration space

Return values

  0 | Hardware doesn't do perfect drain
  1 | Hardware does perfect drain

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.

Perfect drain means that the hardware does not use samples beyond the stream application pointer.

## ◆ snd_pcm_hw_params_malloc()

int snd_pcm_hw_params_malloc | ( | snd_pcm_hw_params_t ** | ptr | ) |

allocate an invalid snd_pcm_hw_params_t using standard malloc

Parameters

  ptr | returned pointer

Returns
  0 on success otherwise negative error code

## ◆ snd_pcm_hw_params_sizeof()

size_t snd_pcm_hw_params_sizeof | ( | void |  | ) |

get size of snd_pcm_hw_params_t

Returns
  size in bytes

## ◆ snd_pcm_hw_params_supports_audio_ts_type()

int snd_pcm_hw_params_supports_audio_ts_type | ( | const snd_pcm_hw_params_t * | params,
|  | int | type )

Check if hardware supports type of audio timestamps.

Parameters

  params | Configuration space
  type | Audio timestamp type

Return values

  0 | Hardware doesn't support type of audio timestamps
  1 | Hardware supports type of audio timestamps

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.

## ◆ snd_pcm_hw_params_supports_audio_wallclock_ts()

int snd_pcm_hw_params_supports_audio_wallclock_ts | ( | const snd_pcm_hw_params_t * | params | ) |

Check if hardware supports audio wallclock timestamps.

Parameters

  params | Configuration space

Return values

  0 | Hardware doesn't support audio wallclock timestamps
  1 | Hardware supports audio wallclock timestamps

This function should only be called when the configuration space contains a single configuration. Call snd_pcm_hw_params to choose a single configuration from the configuration space.