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 );
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.
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.