From 77ebb6567faec67c714c0c91ae1a3bf982197863 Mon Sep 17 00:00:00 2001 From: Tanu Kaskinen Date: Wed, 4 Dec 2013 06:17:11 +0200 Subject: [PATCH] def, format: Document how to leave PCM parameters to be decided by the server --- src/pulse/def.h | 38 +++++++++++++++++++++++++++---- src/pulse/format.h | 56 +++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 85 insertions(+), 9 deletions(-) diff --git a/src/pulse/def.h b/src/pulse/def.h index 58190cb3..a01c9021 100644 --- a/src/pulse/def.h +++ b/src/pulse/def.h @@ -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 diff --git a/src/pulse/format.h b/src/pulse/format.h index e3c8f36c..72846426 100644 --- a/src/pulse/format.h +++ b/src/pulse/format.h @@ -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 -- 2.39.2