mirrors/pulseaudio
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pulseaudio/pulseaudio.git synced 2025-10-29 05:40:23 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

def, format: Document how to leave PCM parameters to be decided by the server

Browse source
This commit is contained in:
Tanu Kaskinen 2013-12-04 06:17:11 +02:00
parent f41650a550
commit 77ebb6567f
2 changed files with 85 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

38
src/pulse/def.h
View file

@ -232,20 +232,50 @@ typedef enum pa_stream_flags {
* specified manual buffer metrics it is recommended to update
* them with pa_stream_set_buffer_attr() to compensate for the
* changed frame sizes. Only supported when the server is at least
* PA 0.9.8. It is ignored on older servers. \since 0.9.8 */
* PA 0.9.8. It is ignored on older servers.
*
* When creating streams with pa_stream_new_extended(), this flag has no
* effect. If you specify a format with PCM encoding, and you want the
* server to choose the sample format, then you should leave the sample
* format unspecified in the pa_format_info object. This also means that
* you can't use pa_format_info_from_sample_spec(), because that function
* always sets the sample format.
*
* \since 0.9.8 */
PA_STREAM_FIX_RATE = 0x0080U,
/**< Use the sample rate of the sink, and possibly ignore the rate
* the sample spec contains. Usage similar to
* PA_STREAM_FIX_FORMAT.Only supported when the server is at least
* PA 0.9.8. It is ignored on older servers. \since 0.9.8 */
* PA_STREAM_FIX_FORMAT. Only supported when the server is at least
* PA 0.9.8. It is ignored on older servers.
*
* When creating streams with pa_stream_new_extended(), this flag has no
* effect. If you specify a format with PCM encoding, and you want the
* server to choose the sample rate, then you should leave the rate
* unspecified in the pa_format_info object. This also means that you can't
* use pa_format_info_from_sample_spec(), because that function always sets
* the sample rate.
*
* \since 0.9.8 */
PA_STREAM_FIX_CHANNELS = 0x0100,
/**< Use the number of channels and the channel map of the sink,
* and possibly ignore the number of channels and the map the
* sample spec and the passed channel map contains. Usage similar
* to PA_STREAM_FIX_FORMAT. Only supported when the server is at
* least PA 0.9.8. It is ignored on older servers. \since 0.9.8 */
* least PA 0.9.8. It is ignored on older servers.
*
* When creating streams with pa_stream_new_extended(), this flag has no
* effect. If you specify a format with PCM encoding, and you want the
* server to choose the channel count and/or channel map, then you should
* leave the channels and/or the channel map unspecified in the
* pa_format_info object. This also means that you can't use
* pa_format_info_from_sample_spec(), because that function always sets
* the channel count (but if you only want to leave the channel map
* unspecified, then pa_format_info_from_sample_spec() works, because it
* accepts a NULL channel map).
*
* \since 0.9.8 */
PA_STREAM_DONT_MOVE = 0x0200U,
/**< Don't allow moving of this stream to another

56
src/pulse/format.h
View file

@ -130,7 +130,18 @@ char *pa_format_info_snprint(char *s, size_t l, const pa_format_info *f);
* \a pa_format_info_snprint() into a pa_format_info structure. \since 1.0 */
pa_format_info* pa_format_info_from_string(const char *str);
/** Utility function to take a \a pa_sample_spec and generate the corresponding \a pa_format_info. \since 2.0 */
/** Utility function to take a \a pa_sample_spec and generate the corresponding
* \a pa_format_info.
*
* Note that if you want the server to choose some of the stream parameters,
* for example the sample rate, so that they match the device parameters, then
* you shouldn't use this function. In order to allow the server to choose
* a parameter value, that parameter must be left unspecified in the
* pa_format_info object, and this function always specifies all parameters. An
* exception is the channel map: if you pass NULL for the channel map, then the
* channel map will be left unspecified, allowing the server to choose it.
*
* \since 2.0 */
pa_format_info* pa_format_info_from_sample_spec(const pa_sample_spec *ss, const pa_channel_map *map);
/** Utility function to generate a \a pa_sample_spec and \a pa_channel_map corresponding to a given \a pa_format_info. The
@ -204,13 +215,48 @@ void pa_format_info_set_prop_string(pa_format_info *f, const char *key, const ch
/** Sets a property with a list of string values on the given format info. \since 1.0 */
void pa_format_info_set_prop_string_array(pa_format_info *f, const char *key, const char **values, int n_values);
/** Convenience method to set the sample format as a property on the given format. \since 1.0 */
/** Convenience method to set the sample format as a property on the given
* format.
*
* Note for PCM: If the sample format is left unspecified in the pa_format_info
* object, then the server will select the stream sample format. In that case
* the stream sample format will most likely match the device sample format,
* meaning that sample format conversion will be avoided.
*
* \since 1.0 */
void pa_format_info_set_sample_format(pa_format_info *f, pa_sample_format_t sf);
/** Convenience method to set the sampling rate as a property on the given format. \since 1.0 */
/** Convenience method to set the sampling rate as a property on the given
* format.
*
* Note for PCM: If the sample rate is left unspecified in the pa_format_info
* object, then the server will select the stream sample rate. In that case the
* stream sample rate will most likely match the device sample rate, meaning
* that sample rate conversion will be avoided.
*
* \since 1.0 */
void pa_format_info_set_rate(pa_format_info *f, int rate);
/** Convenience method to set the number of channels as a property on the given format. \since 1.0 */
/** Convenience method to set the number of channels as a property on the given
* format.
*
* Note for PCM: If the channel count is left unspecified in the pa_format_info
* object, then the server will select the stream channel count. In that case
* the stream channel count will most likely match the device channel count,
* meaning that up/downmixing will be avoided.
*
* \since 1.0 */
void pa_format_info_set_channels(pa_format_info *f, int channels);
/** Convenience method to set the channel map as a property on the given format. \since 1.0 */
/** Convenience method to set the channel map as a property on the given
* format.
*
* Note for PCM: If the channel map is left unspecified in the pa_format_info
* object, then the server will select the stream channel map. In that case the
* stream channel map will most likely match the device channel map, meaning
* that remixing will be avoided.
*
* \since 1.0 */
void pa_format_info_set_channel_map(pa_format_info *f, const pa_channel_map *map);
PA_C_DECL_END