snd_pcm_plugin

Set the configurable parameters for a PCM channel (plugin-aware)

Synopsis:

#include <sys/asoundlib.h>

int snd_pcm_plugin_params( snd_pcm_t *handle, 
                           snd_pcm_channel_params_t *params );

Arguments:

handle: The handle for the PCM device, which you must have opened by calling snd_pcm_open_name(), snd_pcm_open(), or snd_pcm_open_preferred().
params: A pointer to a snd_pcm_channel_params_t structure in which you've specified the PCM channel's configurable parameters. All members are write-only.

Library:

libasound.so

Use the -l asound option with qcc to link against this library.

Description:

The snd_pcm_plugin_params() function sets up the transfer parameters according to params.

You can call the function in SND_PCM_STATUS_NOTREADY (initial) and SND_PCM_STATUS_READY states; otherwise, snd_pcm_plugin_params() returns -EBADFD.

If the parameters are valid (i.e., snd_pcm_plugin_params() returns zero), the driver state is changed to SND_PCM_STATUS_READY.

Note: You can confirm the channel's configuration by reading it back with snd_pcm_plugin_setup().

When you call snd_pcm_plugin_params(), you must provide the fragment size you would like to use. The io-audio services attempts to fulfill the requested fragment size however, many factors cause io-audio to return a size that doesn't exactly match the size that you requested, such as hardware/software alignment restrictions, required data conversions, etc. To determine the actual fragment size that the subchannel is configured for, you must call snd_pcm_plugin_setup().

Note: A software alignment restriction includes interfacing to the PCM Software mixer or PCM Input Splitter which operates at a fixed fragment period. For more information, see “PCM software mixer” and “PCM input splitter.”

Example calculations for requesting a fragment size that holds 16ms of data

In this example the source audio data is 16Khz, 16-bit, mono and the audio playback device is 48Khz, 16-bit stereo:

Fragment size (in bytes) = (16000Hz * 2 bytes * 1 channels * 16ms) / 1000
                         = 512000 / 1000
                         = 512

Because the data's format doesn't match the configuration of the playback device, the libasound library will automatically up convert the data for you. This up conversion will result in your original 512 bytes of data becoming 3072 bytes of data at the device level. You can always base your fragment size on a time period rather than a fixed number of bytes so that you don't have to worry about any required data conversions changing the intended playback timings. For example:

App fragment period       = 512 / (16000 * 2 * 1 / 1000) = 16ms
libasound up conversions  = 512 * (48000/16000 * 2/1) = 3072 bytes
Playback fragment period  = 3072 / (48000 * 2 * 2 / 1000) = 16ms

Returns:

EOK on success, a negative errno upon failure. The errno values are available in the errno.h file.

Errors:

-EINVAL: The state of handle is invalid, the format is unsupported, or an invalid state change occurred. You can call snd_pcm_channel_status() to check if the state change was invalid.

Classification:

QNX Neutrino

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes

Caveats:

This function is not thread safe if handle (snd_pcm_t) is used across multiple threads.

This function is the plugin-aware version of snd_pcm_channel_params() . It functions exactly the same way. However, make sure that you don't mix and match plugin- and nonplugin-aware functions in your application, or you may get undefined behavior and misleading results.