prepare doxygen docs for 0.9.11

8 files changed, 174 insertions, 78 deletions

diff --git a/src/pulse/channelmap.h b/src/pulse/channelmap.h
index 2551eae9..7c32b868 100644
--- a/src/pulse/channelmap.h
+++ b/src/pulse/channelmap.h
@@ -47,8 +47,10 @@
  *
  * \li pa_channel_map_init_mono() - Create a channel map with only mono audio.
  * \li pa_channel_map_init_stereo() - Create a standard stereo mapping.
- * \li pa_channel_map_init_auto() - Create a standard channel map for up to
- *                                  six channels.
+ * \li pa_channel_map_init_auto() - Create a standard channel map for a specific number of channels
+ * \li pa_channel_map_init_extend() - Similar to
+ * pa_channel_map_init_auto() but synthesize a channel map if noone
+ * predefined one is known for the specified number of channels.
  *
  * \section conv_sec Convenience Functions
  *
diff --git a/src/pulse/context.h b/src/pulse/context.h
index 8dff7642..3b513976 100644
--- a/src/pulse/context.h
+++ b/src/pulse/context.h
@@ -35,7 +35,7 @@
  * \section overv_sec Overview
  *
  * The asynchronous API is the native interface to the PulseAudio library.
- * It allows full access to all available functions. This also means that
+ * It allows full access to all available functionality. This however means that
  * it is rather complex and can take some time to fully master.
  *
  * \section mainloop_sec Main Loop Abstraction
@@ -64,8 +64,7 @@
  *                                  implementation where all of PulseAudio's
  *                                  internal handling runs in a separate
  *                                  thread.
- * \li \subpage glib-mainloop - A wrapper around GLIB's main loop. Available
- *                              for both GLIB 1.2 and GLIB 2.x.
+ * \li \subpage glib-mainloop - A wrapper around GLib's main loop.
  *
  * UNIX signals may be hooked to a main loop using the functions from
  * \ref mainloop-signal.h. These rely only on the main loop abstraction
diff --git a/src/pulse/def.h b/src/pulse/def.h
index 8407ddeb..95071978 100644
--- a/src/pulse/def.h
+++ b/src/pulse/def.h
@@ -233,12 +233,11 @@ typedef enum pa_stream_flags {
 
     PA_STREAM_START_MUTED = 4096,  /**< Create in muted state. \since 0.9.11 */
 
-
     PA_STREAM_ADJUST_LATENCY = 8192, /**< Try to adjust the latency of
                                       * the sink/source based on the
                                       * requested buffer metrics and
                                       * adjust buffer metrics
-                                      * accordingly. \since 0.9.11 */
+                                      * accordingly. See pa_buffer_attr \since 0.9.11 */
 } pa_stream_flags_t;
 
 
@@ -248,53 +247,86 @@ typedef enum pa_stream_flags {
 /** Playback and record buffer metrics */
 typedef struct pa_buffer_attr {
     uint32_t maxlength;      /**< Maximum length of the
-                              * buffer. Setting this to 0 will
+                              * buffer. Setting this to (uint32_t) -1 will
                               * initialize this to the maximum value
                               * supported by server, which is
                               * recommended. */
     uint32_t tlength;        /**< Playback only: target length of the
                               * buffer. The server tries to assure
                               * that at least tlength bytes are always
-                              * available in the buffer. It is
-                              * recommended to set this to 0, which
-                              * will initialize this to a value that
-                              * is deemed sensible by the
+                              * available in the per-stream
+                              * server-side playback buffer. It is
+                              * recommended to set this to (uint32_t)
+                              * -1, which will initialize this to a
+                              * value that is deemed sensible by the
                               * server. However, this value will
                               * default to something like 2s, i.e. for
                               * applications that have specific
                               * latency requirements this value should
                               * be set to the maximum latency that the
-                              * application can deal with.  */
+                              * application can deal with. When
+                              * PA_STREAM_ADJUST_LATENCY is not set
+                              * this value will influence only the
+                              * per-stream playback buffer size. When
+                              * PA_STREAM_ADJUST_LATENCY is set the
+                              * overall latency of the sink plus the
+                              * playback buffer size is configured to
+                              * this value. Set
+                              * PA_STREAM_ADJUST_LATENCY if you are
+                              * interested in adjusting the overall
+                              * latency. Don't set it if you are
+                              * interested in configuring the
+                              * server-sider per-stream playback
+                              * buffer size. */
     uint32_t prebuf;         /**< Playback only: pre-buffering. The
                               * server does not start with playback
                               * before at least prebug bytes are
                               * available in the buffer. It is
-                              * recommended to set this to 0, which
-                              * will initialize this to the same value
-                              * as tlength, whatever that may be. */
+                              * recommended to set this to (uint32_t)
+                              * -1, which will initialize this to the
+                              * same value as tlength, whatever that
+                              * may be. Initialize to 0 to enable
+                              * manual start/stop control of the
+                              * stream. This means that playback will
+                              * not stop on underrun and playback will
+                              * not start automatically. Instead
+                              * pa_stream_corked() needs to be called
+                              * explicitly. If you set this value to 0
+                              * you should also set
+                              * PA_STREAM_START_CORKED. */
     uint32_t minreq;         /**< Playback only: minimum request. The
                               * server does not request less than
                               * minreq bytes from the client, instead
                               * waits until the buffer is free enough
                               * to request more bytes at once. It is
-                              * recommended to set this to 0, which
-                              * will initialize this to a value that
-                              * is deemed sensible by the server. */
+                              * recommended to set this to (uint32_t)
+                              * -1, which will initialize this to a
+                              * value that is deemed sensible by the
+                              * server. This should be set to a value
+                              * that gives PulseAudio enough time to
+                              * move the data from the per-stream
+                              * playback buffer into the hardware
+                              * playback buffer. */
     uint32_t fragsize;       /**< Recording only: fragment size. The
                               * server sends data in blocks of
                               * fragsize bytes size. Large values
                               * deminish interactivity with other
                               * operations on the connection context
                               * but decrease control overhead. It is
-                              * recommended to set this to 0, which
-                              * will initialize this to a value that
-                              * is deemed sensible by the
+                              * recommended to set this to (uint32_t)
+                              * -1, which will initialize this to a
+                              * value that is deemed sensible by the
                               * server. However, this value will
                               * default to something like 2s, i.e. for
                               * applications that have specific
                               * latency requirements this value should
                               * be set to the maximum latency that the
-                              * application can deal with. */
+                              * application can deal with. If
+                              * PA_STREAM_ADJUST_LATENCY is set the
+                              * overall source latency will be
+                              * adjusted according to this value. If
+                              * it is not set the source latency is
+                              * left unmodified. */
 } pa_buffer_attr;
 
 /** Error values as used by pa_context_errno(). Use pa_strerror() to convert these values to human readable strings */
@@ -431,9 +463,9 @@ typedef struct pa_timing_info {
                                * PA_SEEK_RELATIVE_ON_READ
                                * instead. */
 
-    pa_usec_t configured_sink_usec;   /**< The static configured latency for
+    pa_usec_t configured_sink_usec;   /**< The configured latency for
                                 * the sink. \since 0.9.11 */
-    pa_usec_t configured_source_usec; /**< The static configured latency for
+    pa_usec_t configured_source_usec; /**< The configured latency for
                                 * the source. \since 0.9.11 */
 
     int64_t since_underrun;    /**< Bytes that were handed to the sink
diff --git a/src/pulse/introspect.h b/src/pulse/introspect.h
index c8c13a75..6a6755e7 100644
--- a/src/pulse/introspect.h
+++ b/src/pulse/introspect.h
@@ -130,8 +130,10 @@
  *
  * \subsection autoload_subsec Autoload Entries
  *
- * Modules can be autoloaded as a result of a client requesting a certain
- * sink or source. This mapping between sink/source names and modules can be
+ * Modules can be autoloaded as a result of a client requesting a
+ * certain sink or source. Please note that autoloading is deprecated
+ * in 0.9.11. and is likely to be removed from the API in a later
+ * version. This mapping between sink/source names and modules can be
  * queried from the server:
  *
  * \li By index - pa_context_get_autoload_info_by_index()
@@ -191,7 +193,9 @@
  *
  * New module autoloading rules can be added, and existing can be removed
  * using pa_context_add_autoload() and pa_context_remove_autoload_by_index()
- * / pa_context_remove_autoload_by_name().
+ * / pa_context_remove_autoload_by_name(). Please note that autoloading is deprecated
+ * in 0.9.11. and is likely to be removed from the API in a later
+ * version.
  *
  * \subsection client_subsec Clients
  *
diff --git a/src/pulse/proplist.h b/src/pulse/proplist.h
index f75cca54..39d53303 100644
--- a/src/pulse/proplist.h
+++ b/src/pulse/proplist.h
@@ -36,19 +36,20 @@ PA_C_DECL_BEGIN
  *    media.artist                  "Guns'N'Roses"
  *    media.language                "de_DE"
  *    media.filename
- *    media.icon
- *    media.icon_name
+ *    media.icon                    Binary blob containing PNG icon data
+ *    media.icon_name               Name from XDG icon naming spec
  *    media.role                    video, music, game, event, phone, production, filter, abstract, stream
- *    event.id                      button-click, session-login
+ *    event.id                      Name from XDG sound naming spec
+ *    event.description             "Button blabla clicked" for a11y
  *    event.mouse.x
  *    event.mouse.y
- *    event.mouse.hpos
- *    event.mouse.vpos
- *    event.mouse.button
+ *    event.mouse.hpos              Float formatted as string in range 0..1
+ *    event.mouse.vpos              Float formatted as string in range 0..1
+ *    event.mouse.button            Button number following X11 ordering
  *    window.name
- *    window.id
- *    window.icon
- *    window.icon_name
+ *    window.id                     "org.gnome.rhytmbox.MainWindow"
+ *    window.icon                   Binary blob containing PNG icon data
+ *    window.icon_name              Name from XDG icon naming spec
  *    window.x11.display
  *    window.x11.screen
  *    window.x11.monitor
@@ -56,23 +57,23 @@ PA_C_DECL_BEGIN
  *    application.name              "Rhythmbox Media Player"
  *    application.id                "org.gnome.rhythmbox"
  *    application.version
- *    application.icon
- *    application.icon_name
+ *    application.icon              Binary blob containing PNG icon data
+ *    application.icon_name         Name from XDG icon naming spec
  *    application.language
  *    application.process.id
  *    application.process.binary
  *    application.process.user
  *    application.process.host
  *    device.string
- *    device.api                     oss, alsa, sunaudio
+ *    device.api                    oss, alsa, sunaudio
  *    device.description
  *    device.bus_path
  *    device.serial
  *    device.vendor_product_id
- *    device.class                   sound, modem, monitor, filter, abstract
- *    device.form_factor             laptop-speakers, external-speakers, telephone, tv-capture, webcam-capture, microphone-capture, headset
- *    device.connector               isa, pci, usb, firewire, bluetooth
- *    device.access_mode             mmap, mmap_rewrite, serial
+ *    device.class                  sound, modem, monitor, filter, abstract
+ *    device.form_factor            laptop-speakers, external-speakers, telephone, tv-capture, webcam-capture, microphone-capture, headset
+ *    device.connector              isa, pci, usb, firewire, bluetooth
+ *    device.access_mode            mmap, mmap_rewrite, serial
  *    device.master_device
  *    device.bufferin.buffer_size
  *    device.bufferin.fragment_size
@@ -86,6 +87,7 @@ PA_C_DECL_BEGIN
 #define PA_PROP_MEDIA_ICON_NAME                "media.icon_name"
 #define PA_PROP_MEDIA_ROLE                     "media.role"
 #define PA_PROP_EVENT_ID                       "event.id"
+#define PA_PROP_EVENT_DESCRIPTION              "event.description"
 #define PA_PROP_EVENT_MOUSE_X                  "event.mouse.x"
 #define PA_PROP_EVENT_MOUSE_Y                  "event.mouse.y"
 #define PA_PROP_EVENT_MOUSE_HPOS               "event.mouse.hpos"
diff --git a/src/pulse/pulseaudio.h b/src/pulse/pulseaudio.h
index 4a4531e6..e09cacaf 100644
--- a/src/pulse/pulseaudio.h
+++ b/src/pulse/pulseaudio.h
@@ -89,17 +89,17 @@
  *
  * \section thread_sec Threads
  *
- * The PulseAudio client libraries are not designed to be used in a
- * heavily threaded environment. They are however designed to be reentrant
- * safe.
+ * The PulseAudio client libraries are not designed to be directly
+ * thread-safe. They are however designed to be reentrant and
+ * threads-aware.
  *
- * To use a the libraries in a threaded environment, you must assure that
+ * To use the libraries in a threaded environment, you must assure that
  * all objects are only used in one thread at a time. Normally, this means
  * that all objects belonging to a single context must be accessed from the
  * same thread.
  *
  * The included main loop implementation is also not thread safe. Take care
- * to make sure event lists are not manipulated when any other code is
+ * to make sure event objects are not manipulated when any other code is
  * using the main loop.
  *
  * \section pkgconfig pkg-config
diff --git a/src/pulse/sample.h b/src/pulse/sample.h
index 1ba3f871..2680cf7e 100644
--- a/src/pulse/sample.h
+++ b/src/pulse/sample.h
@@ -52,7 +52,7 @@
  * \li PA_SAMPLE_S32LE - Signed 32 bit integer PCM, little endian.
  * \li PA_SAMPLE_S32BE - Signed 32 bit integer PCM, big endian.
  *
- * The floating point sample formats have the range from -1 to 1.
+ * The floating point sample formats have the range from -1.0 to 1.0.
  *
  * The sample formats that are sensitive to endianness have convenience
  * macros for native endian (NE), and reverse endian (RE).
diff --git a/src/pulse/stream.h b/src/pulse/stream.h
index fbf0ae44..2a8f7a8b 100644
--- a/src/pulse/stream.h
+++ b/src/pulse/stream.h
@@ -70,35 +70,85 @@
  *
  * \subsection bufattr_subsec Buffer Attributes
  *
- * Playback and record streams always have a server side buffer as
- * part of the data flow.  The size of this buffer strikes a
- * compromise between low latency and sensitivity for buffer
+ * Playback and record streams always have a server-side buffer as
+ * part of the data flow.  The size of this buffer needs to be chosen
+ * in a compromise between low latency and sensitivity for buffer
  * overflows/underruns.
  *
  * The buffer metrics may be controlled by the application. They are
  * described with a pa_buffer_attr structure which contains a number
  * of fields:
  *
- * \li maxlength - The absolute maximum number of bytes that can be stored in
- *                 the buffer. If this value is exceeded then data will be
- *                 lost.
- * \li tlength - The target length of a playback buffer. The server will only
- *               send requests for more data as long as the buffer has less
- *               than this number of bytes of data.
+ * \li maxlength - The absolute maximum number of bytes that can be
+ *                 stored in the buffer. If this value is exceeded
+ *                 then data will be lost. It is recommended to pass
+ *                 (uint32_t) -1 here which will cause the server to
+ *                 fill in the maximum possible value.
+ *
+ * \li tlength - The target fill level of the playback buffer. The
+ *               server will only send requests for more data as long
+ *               as the buffer has less than this number of bytes of
+ *               data. If you pass (uint32_t) -1 (which is
+ *               recommended) here the server will choose the longest
+ *               target buffer fill level possible to minimize the
+ *               number of necessary wakeups and maximize drop-out
+ *               safety. This can exceed 2s of buffering. For
+ *               low-latency applications or applications where
+ *               latency matters you should pass a proper value here.
+ *
  * \li prebuf - Number of bytes that need to be in the buffer before
- * playback will commence. Start of playback can be forced using
- * pa_stream_trigger() even though the prebuffer size hasn't been
- * reached. If a buffer underrun occurs, this prebuffering will be
- * again enabled. If the playback shall never stop in case of a buffer
- * underrun, this value should be set to 0. In that case the read
- * index of the output buffer overtakes the write index, and hence the
- * fill level of the buffer is negative.
- * \li minreq - Minimum free number of the bytes in the playback buffer before
- *              the server will request more data.
- * \li fragsize - Maximum number of bytes that the server will push in one
- *                chunk for record streams.
- *
- * The server side playback buffers are indexed by a write and a read
+ *              playback will commence. Start of playback can be
+ *              forced using pa_stream_trigger() even though the
+ *              prebuffer size hasn't been reached. If a buffer
+ *              underrun occurs, this prebuffering will be again
+ *              enabled. If the playback shall never stop in case of a
+ *              buffer underrun, this value should be set to 0. In
+ *              that case the read index of the output buffer
+ *              overtakes the write index, and hence the fill level of
+ *              the buffer is negative. If you pass (uint32_t) -1 here
+ *              (which is recommended) the server will choose the same
+ *              value as tlength here.
+ *
+ * \li minreq - Minimum free number of the bytes in the playback
+ *              buffer before the server will request more data. It is
+ *              recommended to fill in (uint32_t) -1 here. This value
+ *              influences how much time the sound server has to move
+ *              data from the per-stream server-side playback buffer
+ *              to the hardware playback buffer.
+ *
+ * \li fragsize - Maximum number of bytes that the server will push in
+ *                one chunk for record streams. If you pass (uint32_t)
+ *                -1 (which is recommended) here, the server will
+ *                choose the longest fragment setting possible to
+ *                minimize the number of necessary wakeups and
+ *                maximize drop-out safety. This can exceed 2s of
+ *                buffering. For low-latency applications or
+ *                applications where latency matters you should pass a
+ *                proper value here.
+ *
+ * If PA_STREAM_ADJUST_LATENCY is set, then the tlength/fragsize
+ * parameters will be interpreted slightly differently than described
+ * above when passed to pa_stream_connect_record() and
+ * pa_stream_connect_playback(): the overall latency that is comprised
+ * of both the server side playback buffer length, the hardware
+ * playback buffer length and additional latencies will be adjusted in
+ * a way that it matches tlength resp. fragsize. Set
+ * PA_STREAM_ADJUST_LATENCY if you want to control the overall
+ * playback latency for your stream. Unset it if you want to control
+ * only the latency induced by the server-side, rewritable playback
+ * buffer. The server will try to fulfill the clients latency requests
+ * as good as possible. However if the underlying hardware cannot
+ * change the hardware buffer length or only in a limited range, the
+ * actually resulting latency might be different from what the client
+ * requested. Thus, for synchronization clients always need to check
+ * the actual measured latency via pa_stream_get_latency() or a
+ * similar call, and not make any assumptions. about the latency
+ * available. The function pa_stream_get_buffer_attr() will always
+ * return the actual size of the server-side per-stream buffer in
+ * tlength/fragsize, regardless whether PA_STREAM_ADJUST_LATENCY is
+ * set or not.
+ *
+ * The server-side per-stream playback buffers are indexed by a write and a read
  * index. The application writes to the write index and the sound
  * device reads from the read index. The read index is increased
  * monotonically, while the write index may be freely controlled by
@@ -196,10 +246,10 @@
  * accordingly.
  *
  * The raw timing data in the pa_timing_info structure is usually hard
- * to deal with. Therefore a more simplistic interface is available:
+ * to deal with. Therefore a simpler interface is available:
  * you can call pa_stream_get_time() or pa_stream_get_latency(). The
  * former will return the current playback time of the hardware since
- * the stream has been started. The latter returns the time a sample
+ * the stream has been started. The latter returns the overall time a sample
  * that you write now takes to be played by the hardware. These two
  * functions base their calculations on the same data that is returned
  * by pa_stream_get_timing_info(). Hence the same rules for keeping
@@ -512,9 +562,14 @@ const pa_sample_spec* pa_stream_get_sample_spec(pa_stream *s);
 /** Return a pointer to the stream's channel map. */
 const pa_channel_map* pa_stream_get_channel_map(pa_stream *s);
 
-/** Return the buffer metrics of the stream. Only valid after the
- * stream has been connected successfuly and if the server is at least
- * PulseAudio 0.9. \since 0.9.0 */
+/** Return the per-stream server-side buffer metrics of the
+ * stream. Only valid after the stream has been connected successfuly
+ * and if the server is at least PulseAudio 0.9. This will return the
+ * actual configured buffering metrics, which may differ from what was
+ * requested during pa_stream_connect_record() or
+ * pa_stream_connect_playback(). This call will always return the
+ * actually per-stream server-side buffer metrics, regardless whether
+ * PA_STREAM_ADJUST_LATENCY is set or not. \since 0.9.0 */
 const pa_buffer_attr* pa_stream_get_buffer_attr(pa_stream *s);
 
 /** Change the buffer metrics of the stream during playback. The
@@ -522,7 +577,9 @@ const pa_buffer_attr* pa_stream_get_buffer_attr(pa_stream *s);
  * requested. The selected metrics may be queried with
  * pa_stream_get_buffer_attr() as soon as the callback is called. Only
  * valid after the stream has been connected successfully and if the
- * server is at least PulseAudio 0.9.8. \since 0.9.8 */
+ * server is at least PulseAudio 0.9.8. Please be aware of the
+ * slightly different semantics of the call depending whether
+ * PA_STREAM_ADJUST_LATENCY is set or not. \since 0.9.8 */
 pa_operation *pa_stream_set_buffer_attr(pa_stream *s, const pa_buffer_attr *attr, pa_stream_success_cb_t cb, void *userdata);
 
 /** Change the stream sampling rate during playback. You need to pass