summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2009-10-28 23:47:50 +0100
committerLennart Poettering <lennart@poettering.net>2009-11-11 05:13:47 +0100
commit3dcdab6e8d84c0b8941051c9b95d7e73a65ce15c (patch)
tree95485df88dc0be9d2e1740ea266663c69d56c7ff
parent0c31723a8b4428b518a0bb60e3140a30fdec318f (diff)
libpulse: explain semantics of pa_stream_connect_playback() in more detail
-rw-r--r--src/pulse/stream.h17
1 files changed, 16 insertions, 1 deletions
diff --git a/src/pulse/stream.h b/src/pulse/stream.h
index 2e8e71a0..bc54a118 100644
--- a/src/pulse/stream.h
+++ b/src/pulse/stream.h
@@ -401,7 +401,22 @@ int pa_stream_is_suspended(pa_stream *s);
* not, and negative on error. \since 0.9.11 */
int pa_stream_is_corked(pa_stream *s);
-/** Connect the stream to a sink */
+/** Connect the stream to a sink. It is strongly recommended to pass
+ * NULL in both dev and volume and not to set either
+ * PA_STREAM_START_MUTED nor PA_STREAM_START_UNMUTED -- unless these
+ * options are directly dependant on user input or configuration. If
+ * you follow this rule then the sound server will have the full
+ * flexibility to choose the device, volume and mute status
+ * automatically, based on server-side policies, heuristics and stored
+ * information from previous uses. Also the server may choose to
+ * reconfigure audio devices to make other sinks/sources or
+ * capabilities available to be able to accept the stream. Before
+ * 0.9.20 it was not defined whether the 'volume' parameter was
+ * interpreted relative to the sink's current volume or treated as
+ * absolute device volume. Since 0.9.20 it is an absolute volume when
+ * the sink is in flat volume mode, and relative otherwise, thus
+ * making sure the volume passed here has always the same semantics as
+ * the volume passed to pa_context_set_sink_input_volume(). */
int pa_stream_connect_playback(
pa_stream *s /**< The stream to connect to a sink */,
const char *dev /**< Name of the sink to connect to, or NULL for default */ ,