Big documentation update. Describe the client API in a more tutorial like

manner.


git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@667 fefdeb5f-60dc-0310-8127-8f9354f1896f

src/polyp/channelmap.h

@@ -25,6 +25,40 @@
 #include <polyp/sample.h>
 #include <polyp/cdecl.h>
 
+/** \page channelmap Channel maps
+ *
+ * \section overv_sec Overview
+ *
+ * Channel maps provide a way to associate channels in a stream with a
+ * speaker. This relieves applications of having to make sure their channel
+ * order is identical to the final output.
+ *
+ * \section init_sec Initialisation
+ *
+ * A channel map consists of an array of \ref pa_channel_position values,
+ * one for each channel. This array is stored together with a channel count
+ * in a pa_channel_map structure.
+ *
+ * Before filling the structure, the application must initialise it using
+ * pa_channel_map_init(). There are also a number of convenience functions
+ * for standard channel mappings:
+ *
+ * \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.
+ *
+ * \section conv_sec Convenience functions
+ *
+ * The library contains a number of convenience functions for dealing with
+ * channel maps:
+ *
+ * \li pa_channel_map_valid() - Tests if a channel map is valid.
+ * \li pa_channel_map_equal() - Tests if two channel maps are identical.
+ * \li pa_channel_map_snprint() - Creates a textual description of a channel
+ *                                map.
+ */
+
 /** \file
  * Constants and routines for channel mapping handling */
 

src/polyp/context.h

@@ -28,18 +28,116 @@
 #include <polyp/cdecl.h>
 #include <polyp/operation.h>
 
+/** \page async Asynchronous API
+ *
+ * \section overv_sec Overview
+ *
+ * The asynchronous API is the native interface to the polypaudio library.
+ * It allows full access to all available functions. This also means that
+ * it is rather complex and can take some time to fully master.
+ *
+ * \section mainloop_sec Main loop abstraction
+ *
+ * The API is based around an asynchronous event loop, or main loop,
+ * abstraction. This abstraction contains three basic elements:
+ *
+ * \li Deferred events - Events that trigger each iteration of the main loop.
+ * \li I/O events - Events that trigger on file descriptor activities.
+ * \li Times events - Events that trigger after a fixed ammount of time.
+ *
+ * The abstraction is represented as a number of function pointers in the
+ * pa_mainloop_api structure.
+ *
+ * To actually be able to use these functions, an actual implementation
+ * be coupled to the abstraction. There are two of these shipped with
+ * polypaudio, but any other can be used with a minimal ammount of work,
+ * provided it supports the three basic events listed above.
+ *
+ * The implementations shipped with polypaudio are:
+ *
+ * \li \subpage mainloop - A minimal but fast implementation based on poll().
+ * \li \subpage glib-mainloop - A wrapper around GLIB's main loop. Available
+ *                              for both GLIB 1.2 and GLIB 2.x.
+ *
+ * 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
+ * and can therefore be used with any of the implementations.
+ *
+ * \section refcnt_sec Reference counting
+ *
+ * Almost all objects in polypaudio are reference counted. What that means
+ * is that you rarely malloc() or free() any objects. Instead you increase
+ * and decrease their reference counts. Whenever an object's reference
+ * count reaches zero, that object gets destroy and any resources it uses
+ * get freed.
+ * 
+ * The benefit of this design is that an application need not worry about
+ * whether or not it needs to keep an object around in case the library is
+ * using it internally. If it is, then it has made sure it has its own
+ * reference to it.
+ *
+ * Whenever the library creates an object, it will have an initial
+ * reference count of one. Most of the time, this single reference will be
+ * sufficient for the application, so all required reference count
+ * interaction will be a single call to the objects unref function.
+ *
+ * \section context_sec Context
+ *
+ * A context is the basic object for a connection to a polypaudio server.
+ * It multiplexes commands, data streams and events through a single
+ * channel.
+ *
+ * There is no need for more than one context per application, unless
+ * connections to multiple servers is needed.
+ *
+ * \subsection ops_subsec Operations
+ *
+ * All operations on the context is performed asynchronously. I.e. the
+ * client will not wait for the server to complete the request. To keep
+ * track of all these in-flight operations, the application is given a
+ * pa_operation object for each asynchronous operation.
+ *
+ * There are only two actions (besides reference counting) that can be
+ * performed on a pa_operation: querying its state with
+ * pa_operation_get_state() and aborting it with pa_operation_cancel().
+ *
+ * A pa_operation object is reference counted, so an application must
+ * make sure to unreference it, even if it has no intention of using it.
+ *
+ * \subsection conn_subsec Connecting
+ *
+ * A context must be connected to a server before any operation can be
+ * issued. Calling pa_context_connect() will initiate the connection
+ * procedure. Unlike most asynchronous operations, connecting does not
+ * result in a pa_operation object. Instead, the application should
+ * register a callback using pa_context_set_state_callback().
+ *
+ * \subsection disc_subsec Disconnecting
+ *
+ * When the sound support is no longer needed, the connection needs to be
+ * closed using pa_context_disconnect(). This is an immediate function that
+ * works synchronously.
+ *
+ * Since the context object has references to other objects it must be
+ * disconnected after use or there is a high risk of memory leaks. If the
+ * connection has terminated by itself, then there is no need to explicitly
+ * disconnect the context using pa_context_disconnect().
+ *
+ * \section Functions
+ *
+ * The sound server's functionality can be divided into a number of
+ * subsections:
+ *
+ * \li \subpage streams
+ * \li \subpage scache
+ * \li \subpage introspect
+ * \li \subpage subscribe
+ */
+
 /** \file
  * Connection contexts for asynchrononous communication with a
  * server. A pa_context object wraps a connection to a polypaudio
- * server using its native protocol. A context may be used to issue
+ * server using its native protocol. */
- * commands on the server or to create playback or recording
- * streams. Multiple playback streams may be piped through a single
- * connection context. Operations on the contect involving
- * communication with the server are executed asynchronously: i.e. the
- * client function do not implicitely wait for completion of the
- * operation on the server. Instead the caller specifies a call back
- * function that is called when the operation is completed. Currently
- * running operations may be canceled using pa_operation_cancel(). */
 
 /** \example pacat.c
  * A playback and recording tool using the asynchronous API */

src/polyp/glib-mainloop.h

@@ -27,6 +27,17 @@
 #include <polyp/mainloop-api.h>
 #include <polyp/cdecl.h>
 
+/** \page glib-mainloop GLIB main loop bindings
+ *
+ * \section overv_sec Overview
+ *
+ * The GLIB main loop bindings are extremely easy to use. All that is
+ * required is to create a pa_glib_mainloop object using
+ * pa_glib_mainloop_new(). When the main loop abstraction is needed, it is
+ * provided by pa_glib_mainloop_get_api().
+ *
+ */
+
 /** \file
  * GLIB main loop support */
 

src/polyp/introspect.h

@@ -30,22 +30,176 @@
 #include <polyp/channelmap.h>
 #include <polyp/volume.h>
 
+/** \page introspect Server query and control
+ *
+ * \section overv_sec Overview
+ *
+ * Sometimes it is necessary to query and modify global settings in the
+ * server. For this, Polypaudio has the introspection API. It can list sinks,
+ * sources, samples and other aspects of the server. It can also modify the
+ * attributes of the server that will affect operations on a global level,
+ * and not just the application's context.
+ *
+ * \section query_sec Querying
+ *
+ * All querying is done through callbacks. This design is necessary to
+ * maintain an asynchronous design. The client will request the information
+ * and some time later, the server will respond with the desired data.
+ *
+ * Some objects can have multiple entries at the server. When requesting all
+ * of these at once, the callback will be called multiple times, once for
+ * each object. When the list has been exhausted, the callback will be called
+ * without an information structure and the eol parameter set to a non-zero
+ * value.
+ *
+ * Note that even if a single object is requested, and not the entire list,
+ * the terminating call will still be made.
+ *
+ * If an error occurs, the callback will be called without and information
+ * structure and eol set to zero.
+ *
+ * Data members in the information structures are only valid during the
+ * duration of the callback. If they are required after the callback is
+ * finished, a deep copy must be performed.
+ *
+ * \subsection server_subsec Server information
+ *
+ * The server can be queried about its name, the environment it's running on
+ * and the currently active global defaults. Calling
+ * pa_context_get_server_info() will get access to a pa_server_info structure
+ * containing all of these.
+ *
+ * \subsection memstat_subsec Memory usage
+ *
+ * Statistics about memory usage can be fetched using pa_context_stat(),
+ * giving a pa_stat_info structure.
+ *
+ * \subsection sinksrc_subsec Sinks and sources
+ *
+ * The server can have an arbitrary number of sinks and sources. Each sink
+ * and source have both an index and a name associated with it. As such
+ * there are three ways to get access to them:
+ *
+ * \li By index - pa_context_get_sink_info_by_index() /
+ *                pa_context_get_source_info_by_index()
+ * \li By name - pa_context_get_sink_info_by_name() /
+ *               pa_context_get_source_info_by_name()
+ * \li All - pa_context_get_sink_info_list() /
+ *           pa_context_get_source_info_list()
+ *
+ * All three method use the same callback and will provide a pa_sink_info or
+ * pa_source_info structure.
+ *
+ * \subsection siso_subsec Sink inputs and source outputs
+ *
+ * Sink inputs and source outputs are the representations of the client ends
+ * of streams inside the server. I.e. they connect a client stream to one of
+ * the global sinks or sources.
+ *
+ * Sink inputs and source outputs only have an index to identify them. As
+ * such, there are only two ways to get information about them:
+ *
+ * \li By index - pa_context_get_sink_input_info() /
+ *                pa_context_get_source_output_info()
+ * \li All - pa_context_get_sink_input_info_list() /
+ *           pa_context_get_source_output_info_list()
+ *
+ * The structure returned is the pa_sink_input_info or pa_source_output_info
+ * structure.
+ *
+ * \subsection samples_subsec Samples
+ *
+ * The list of cached samples can be retrieved from the server. Three methods
+ * exist for querying the sample cache list:
+ *
+ * \li By index - pa_context_get_sample_info_by_index()
+ * \li By name - pa_context_get_sample_info_by_name()
+ * \li All - pa_context_get_sample_info_list()
+ *
+ * Note that this only retrieves information about the sample, not the sample
+ * data itself.
+ *
+ * \subsection module_subsec Modules
+ *
+ * Polypaudio modules are identified by index and are retrieved using either
+ * pa_context_get_module_info() or pa_context_get_module_info_list(). The
+ * information structure is called pa_module_info.
+ *
+ * \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
+ * queried from the server:
+ *
+ * \li By index - pa_context_get_autoload_info_by_index()
+ * \li By sink/source name - pa_context_get_autoload_info_by_name()
+ * \li All - pa_context_get_autoload_info_list()
+ *
+ * \subsection client_subsec Clients
+ *
+ * Polypaudio clients are also identified by index and are retrieved using
+ * either pa_context_get_client_info() or pa_context_get_client_info_list().
+ * The information structure is called pa_client_info.
+ *
+ * \section ctrl_sec Control
+ *
+ * Some parts of the server are only possible to read, but most can also be
+ * modified in different ways. Note that these changes will affect all
+ * connected clients and not just the one issuing the request.
+ *
+ * \subsection sinksrc_subsec Sinks and sources
+ *
+ * The most common change one would want to do to sinks and sources is to
+ * modify the volume of the audio. Identical to how sinks and sources can
+ * be queried, there are two ways of identifying them:
+ *
+ * \li By index - pa_context_set_sink_volume_by_index() /
+ *                pa_context_set_source_volume_by_index()
+ * \li By name - pa_context_set_sink_volume_by_name() /
+ *               pa_context_set_source_volume_by_name()
+ *
+ * It is also possible to mute a sink or source:
+ *
+ * \li By index - pa_context_set_sink_mute_by_index() /
+ *                pa_context_set_source_mute_by_index()
+ * \li By name - pa_context_set_sink_mute_by_name() /
+ *               pa_context_set_source_mute_by_name()
+ *
+ * \subsection siso_subsec Sink inputs and source outputs
+ *
+ * If an application desires to modify the volume of just a single stream
+ * (commonly one of its own streams), this can be done by setting the volume
+ * of its associated sink input, using pa_context_set_sink_input_volume().
+ *
+ * There is no support for modifying the volume of source outputs.
+ *
+ * It is also possible to remove sink inputs and source outputs, terminating
+ * the streams associated with them:
+ *
+ * \li Sink input - pa_context_kill_sink_input()
+ * \li Source output - pa_context_kill_source_output()
+ *
+ * \subsection module_subsec Modules
+ *
+ * Server modules can be remotely loaded and unloaded using
+ * pa_context_load_module() and pa_context_unload_module().
+ *
+ * \subsection autoload_subsec Autoload entries
+ *
+ * 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().
+ *
+ * \subsection client_subsec Clients
+ *
+ * The only operation supported on clients, is the possibility of kicking
+ * them off the server using pa_context_kill_client().
+ */
+
 /** \file
  *
- * Routines for daemon introspection. When enumerating all entitites
+ * Routines for daemon introspection.
- * of a certain kind, use the pa_context_xxx_list() functions. The
+ */
- * specified callback function is called once for each entry. The
- * enumeration is finished by a call to the callback function with
- * eol=1 and i=NULL. Strings referenced in pa_xxx_info structures and
- * the structures themselves point to internal memory that may not be
- * modified. That memory is only valid during the call to the callback
- * function. A deep copy is required if you need this data outside the
- * callback functions. An error is signalled by a call to the callback
- * function with i=NULL and eol=0.
- *
- * When using the routines that ask fo a single entry only, a callback
- * with the same signature is used. However, no finishing call to the
- * routine is issued. */
 
 PA_C_DECL_BEGIN
 
@@ -121,7 +275,7 @@ typedef struct pa_server_info {
 
 /** Callback prototype for pa_context_get_server_info() */
 typedef void (*pa_server_info_cb_t) (pa_context *c, const pa_server_info*i, void *userdata);
-
+context_
 /** Get some information about the server */
 pa_operation* pa_context_get_server_info(pa_context *c, pa_server_info_cb_t cb, void *userdata);
 

src/polyp/mainloop.h

@@ -27,6 +27,41 @@
 
 PA_C_DECL_BEGIN
 
+/** \page mainloop Mainloop
+ *
+ * \section overv_sec Overview
+ *
+ * The built-in main loop implementation is based on the poll() system call.
+ * It supports the functions defined in the main loop abstraction and very
+ * little else.
+ *
+ * The main loop is created using pa_mainloop_new() and destroyed using
+ * pa_mainloop_free(). To get access to the main loop abstraction,
+ * pa_mainloop_get_api() is used.
+ *
+ * \section iter_sec Iteration
+ *
+ * The main loop is designed around the concept of iterations. Each iteration
+ * consists of three steps that repeat during the application's entire
+ * lifetime:
+ *
+ * -# Prepare - Dispatch deferred events, build a list of file descriptors
+ *               that need to be monitored and calculate the next timeout.
+ * -# Poll - Execute the actuall poll() system call.
+ * -# Dispatch - Dispatch any timeouts and file descriptors that have fired.
+ *
+ * When using the main loop, the application can either execute each
+ * iteration, one at a time, using pa_mainloop_iterate(), or let the library
+ * iterate automatically using pa_mainloop_run().
+ *
+ * \section thread_sec Threads
+ *
+ * The main loop functions are designed to be thread safe, but the objects
+ * are not. What this means is that multiple main loops can be used, but only
+ * one object per thread.
+ *
+ */
+
 /** \file
  * 
  * A minimal main loop implementation based on the C library's poll()

src/polyp/polypaudio.h

@@ -48,43 +48,49 @@
  * \section intro_sec Introduction
  * 
  * This document describes the client API for the polypaudio sound
- * server. The API comes in two flavours:
+ * server. The API comes in two flavours to accomodate different styles
+ * of applications and different needs in complexity:
  * 
  * \li The complete but somewhat complicated to use asynchronous API
- * \li And the simplified, easy to use, but limited synchronous API
+ * \li The simplified, easy to use, but limited synchronous API
  *
- * The polypaudio client libraries are thread safe as long as all
- * objects created by any library function are accessed from the thread
- * that created them only.
- * 
  * \section simple_sec Simple API
  *
  * Use this if you develop your program in synchronous style and just
  * need a way to play or record data on the sound server. See
- * \ref simple.h for more details.
+ * \subpage simple for more details.
  *
- * \section async_api Asynchronous API
+ * \section async_sec Asynchronous API
  *
- * Use this if you develop your programs in asynchronous, main loop
+ * Use this if you develop your programs in asynchronous, event loop
- * based style or want to use advanced features of the polypaudio
+ * based style or if you want to use the advanced features of the
- * API. A good starting point is \ref context.h
+ * polypaudio API. A guide can be found in \subpage async.
  *
- * The asynchronous API relies on an abstract main loop API that is
+ * \section thread_sec Threads
- * described in \ref mainloop-api.h. Two distinct implementations are
- * available:
- * 
- * \li \ref mainloop.h : a minimal but fast implementation based on poll()
- * \li \ref glib-mainloop.h : a wrapper around GLIB's main loop
  *
- * UNIX signals may be hooked to a main loop using the functions from
+ * The polypaudio client libraries are not designed to be used in a
- * \ref mainloop-signal.h
+ * heavily threaded environment. They are however designed to be reentrant
+ * safe.
+ *
+ * To use a the libraries in a threaded environment, you must assure that
+ * all objects are only used in the same thread they were created in.
+ * 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 library code is
+ * using the main loop.
  *
  * \section pkgconfig pkg-config
  *
- * The polypaudio libraries provide pkg-config snippets for the different modules. To use the
+ * The polypaudio libraries provide pkg-config snippets for the different
- * asynchronous API use "polyplib" as pkg-config file. GLIB main loop
+ * modules:
- * support is available as "glib-mainloop". The simple
+ *
- * synchronous API is available as "simple".
+ * \li polyplib - The asynchronous API and the internal main loop
+ *                implementation.
+ * \li polyplib-glib12-mainloop - GLIB 1.2 main loop bindings.
+ * \li polyplib-glib-mainloop - GLIB 2.x main loop bindings.
+ * \li polyplib-simple - The simple polypaudio API.
  */
 
 #endif

src/polyp/sample.h

@@ -28,6 +28,72 @@
 
 #include <polyp/cdecl.h>
 
+/** \page sample Sample format specifications
+ *
+ * \section overv_sec Overview
+ *
+ * Polypaudio is capable of handling a multitude of sample formats, rates
+ * and channels, transparently converting and mixing them as needed.
+ *
+ * \section format_sec Sample format
+ *
+ * Polypaudio supports the following sample formats:
+ *
+ * \li PA_SAMPLE_U8 - Unsigned 8 bit PCM.
+ * \li PA_SAMPLE_S16LE - Signed 16 bit PCM, little endian.
+ * \li PA_SAMPLE_S16BE - Signed 16 bit PCM, big endian.
+ * \li PA_SAMPLE_FLOAT32LE - 32 bit IEEE floating point PCM, little endian.
+ * \li PA_SAMPLE_FLOAT32BE - 32 bit IEEE floating point PCM, big endian.
+ * \li PA_SAMPLE_ALAW - 8 bit a-Law.
+ * \li PA_SAMPLE_ULAW - 8 bit mu-Law.
+ *
+ * The floating point sample formats have the range from -1 to 1.
+ *
+ * The sample formats that are sensitive to endianness have convenience
+ * macros for native endian (NE), and reverse endian (RE).
+ *
+ * \section rate_sec Sample rates
+ *
+ * Polypaudio supports any sample rate between 1 Hz and 4 GHz. There is no
+ * point trying to exceed the sample rate of the output device though as the
+ * signal will only get downsampled, consuming CPU on the machine running the
+ * server.
+ *
+ * \section chan_sec Channels
+ *
+ * Polypaudio supports up to 16 individiual channels. The order of the
+ * channels is up to the application, but they must be continous. To map
+ * channels to speakers, see \ref channelmap.
+ *
+ * \section calc_sec Calculations
+ *
+ * The Polypaudio library contains a number of convenience functions to do
+ * calculations on sample formats:
+ *
+ * \li pa_bytes_per_second() - The number of bytes one second of audio will
+ *                             take given a sample format.
+ * \li pa_frame_size() - The size, in bytes, of one frame (i.e. one set of
+ *                       samples, one for each channel).
+ * \li pa_sample_size() - The size, in bytes, of one sample.
+ * \li pa_bytes_to_usec() - Calculate the time it would take to play a buffer
+ *                          of a certain size.
+ *
+ * \section util_sec Convenience functions
+ *
+ * The library also contains a couple of other convenience functions:
+ *
+ * \li pa_sample_spec_valid() - Tests if a sample format specification is
+ *                              valid.
+ * \li pa_sample_spec_equal() - Tests if the sample format specifications are
+ *                              identical.
+ * \li pa_sample_format_to_string() - Return a textual description of a
+ *                                    sample format.
+ * \li pa_parse_sample_format() - Parse a text string into a sample format.
+ * \li pa_sample_spec_snprint() - Create a textual description of a complete
+ *                                 sample format specification.
+ * \li pa_bytes_snprint() - Pretty print a byte value (e.g. 2.5 MB).
+ */
+
 /** \file
  * Constants and routines for sample type handling */
 

src/polyp/scache.h

@@ -28,6 +28,49 @@
 #include <polyp/stream.h>
 #include <polyp/cdecl.h>
 
+/** \page scache Sample cache
+ *
+ * \section overv_sec Overview
+ *
+ * The sample cache provides a simple way of overcoming high network latencies
+ * and reducing bandwidth. Instead of streaming a sound precisely when it
+ * should be played, it is stored on the server and only the command to start
+ * playing it needs to be sent.
+ *
+ * \section create_sec Creation
+ *
+ * To create a sample, the normal stream API is used (see \ref streams). The
+ * function pa_stream_connect_upload() will make sure the stream is stored as
+ * a sample on the server.
+ *
+ * To complete the upload, pa_stream_finish_upload() is called and the sample
+ * will receive the same name as the stream. If the upload should be aborted,
+ * simply call pa_stream_disconnect().
+ *
+ * \section play_sec Playing samples
+ *
+ * To play back a sample, simply call pa_context_play_sample():
+ *
+ * \code
+ * pa_operation *o;
+ *
+ * o = pa_context_play_sample(my_context,
+ *                            "sample2",       // Name of my sample
+ *                            NULL,            // Use default sink
+ *                            PA_VOLUME_NORM,  // Full volume
+ *                            NULL,            // Don't need a callback
+ *                            NULL
+ *                            );
+ * if (o)
+ *     pa_operation_unref(o);
+ * \endcode
+ *
+ * \section rem_sec Removing samples
+ *
+ * When a sample is no longer needed, it should be removed on the server to
+ * save resources. The sample is deleted using pa_context_remove_sample().
+ */
+
 /** \file
  * All sample cache related routines */
 

src/polyp/simple.h

@@ -28,9 +28,72 @@
 #include <polyp/def.h>
 #include <polyp/cdecl.h>
 
+/** \page simple Simple API
+ *
+ * \section overv_sec Overview
+ *
+ * The simple API is designed for applications with very basic sound
+ * playback or capture needs. It can only support a single stream per
+ * connection and has no handling of complex features like events, channel
+ * mappings and volume control. It is, however, very simple to use and
+ * quite sufficent for many programs.
+ *
+ * \section conn_sec Connecting
+ *
+ * The first step before using the sound system is to connect to the
+ * server. This is normally done this way:
+ *
+ * \code
+ * pa_simple *s;
+ * pa_sample_spec ss;
+ *
+ * ss.format = S16_NE;
+ * ss.channels = 2;
+ * ss.rate = 44100;
+ *
+ * s = pa_simple_new(NULL,               // Use the default server.
+ *                   "Fooapp",           // Our application's name.
+ *                   PA_STREAM_PLAYBACK,
+ *                   NULL,               // Use the default device.
+ *                   "Music",            // Description of our stream.
+ *                   &ss,                // Our sample format.
+ *                   NULL,               // Use default buffering attributes.
+ *                   NULL,               // Ignore error code.
+ *                   );
+ * \endcode
+ *
+ * At this point a connected object is returned, or NULL if there was a
+ * problem connecting.
+ *
+ * \section transfer_sec Transferring data
+ *
+ * Once the connection is established to the server, data can start flowing.
+ * Using the connection is very similar to the normal read() and write()
+ * system calls. The main difference is that they're call pa_simple_read()
+ * and pa_simple_write(). Note that these operation are always blocking.
+ *
+ * \section ctrl_sec Buffer control
+ *
+ * If a playback stream is used then a few other operations are available:
+ *
+ * \li pa_simple_drain() - Will wait for all sent data to finish playing.
+ * \li pa_simple_flush() - Will throw away all data currently in buffers.
+ * \li pa_simple_get_playback_latency() - Will return the total latency of
+ *                                        the playback pipeline.
+ *
+ * \section cleanup_sec Cleanup
+ *
+ * Once playback or capture is complete, the connection should be closed
+ * and resources freed. This is done through:
+ *
+ * \code
+ * pa_simple_free(s);
+ * \endcode
+ */
+
 /** \file
  * A simple but limited synchronous playback and recording
- * API. This is synchronouse, simplified wrapper around the standard
+ * API. This is a synchronous, simplified wrapper around the standard
  * asynchronous API. */
 
 /** \example pacat-simple.c

src/polyp/stream.h

@@ -31,6 +31,137 @@
 #include <polyp/cdecl.h>
 #include <polyp/operation.h>
 
+/** \page streams Audio streams
+ *
+ * \section overv_sec Overview
+ *
+ * Audio streams form the central functionality of the sound server. Data is
+ * routed, converted and mixed from several sources before it is passed along
+ * to a final output. Currently, there are three forms of audio streams:
+ *
+ * \li Playback streams - Data flows from the client to the server.
+ * \li Record streams - Data flows from the server to the client.
+ * \li Upload streams - Similar to playback streams, but the data is stored in
+ *                      the sample cache. See \ref scache for more information
+ *                      about controlling the sample cache.
+ *
+ * \section create_sec Creating
+ *
+ * To access a stream, a pa_stream object must be created using
+ * pa_stream_new(). At this point the audio sample format and mapping of
+ * channels must be specified. See \ref sample and \ref channelmap for more
+ * information about those structures.
+ *
+ * This first step will only create a client-side object, representing the
+ * stream. To use the stream, a server-side object must be created and
+ * associated with the local object. Depending on which type of stream is
+ * desired, a different function is needed:
+ *
+ * \li Playback stream - pa_stream_connect_playback()
+ * \li Record stream - pa_stream_connect_record()
+ * \li Upload stream - pa_stream_connect_upload() (see \ref scache)
+ *
+ * Similar to how connections are done in contexts, connecting a stream will
+ * not generate a pa_operation object. Also like contexts, the application
+ * should register a state change callback, using
+ * pa_stream_set_state_callback(), and wait for the stream to enter an active
+ * state.
+ *
+ * \subsection bufattr_subsec Buffer attributes
+ *
+ * Playback and record streams always have a buffer as part of the data flow.
+ * The size of this buffer strikes a compromise between low latency and
+ * sensitivity for buffer overflows/underruns.
+ *
+ * The buffer is described with a pa_buffer_attr structure which contains a
+ * number of field:
+ *
+ * \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 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.
+ * \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.
+ *
+ * \section transfer_sec Transferring data
+ *
+ * Once the stream is up, data can start flowing between the client and the
+ * server. Two different access models can be used to transfer the data:
+ *
+ * \li Asynchronous - The application register a callback using
+ *                    pa_stream_set_write_callback() and
+ *                    pa_stream_set_read_callback() to receive notifications
+ *                    that data can either be written or read.
+ * \li Polled - Query the library for available data/space using
+ *              pa_stream_writable_size() and pa_stream_readable_size() and
+ *              transfer data as needed. The sizes are stored locally, in the
+ *              client end, so there is no delay when reading them.
+ *
+ * It is also possible to mix the two models freely.
+ *
+ * Once there is data/space available, it can be transferred using either
+ * pa_stream_write() for playback, or pa_stream_peek() / pa_stream_drop() for
+ * record. Make sure you do not overflow the playback buffers as data will be
+ * dropped.
+ *
+ * \section bufctl_sec Buffer control
+ *
+ * The transfer buffers can be controlled through a number of operations:
+ *
+ * \li pa_stream_cork() - Start or stop the playback or recording.
+ * \li pa_stream_trigger() - Start playback immediatly and do not wait for
+ *                           the buffer to fill up to the set trigger level.
+ * \li pa_stream_prebuf() - Reenable the playback trigger level.
+ * \li pa_stream_drain() - Wait for the playback buffer to go empty. Will
+ *                         return a pa_operation object that will indicate when
+ *                         the buffer is completely drained.
+ * \li pa_stream_flush() - Drop all data from the playback buffer and do not
+ *                         wait for it to finish playing.
+ *
+ * \section latency_sec Latency
+ *
+ * A major problem with networked audio is the increased latency caused by
+ * the network. To remedy this, Polypaudio supports an advanced system of
+ * monitoring the current latency.
+ *
+ * To get the raw data needed to calculate latencies, call
+ * pa_stream_get_timing_info(). This will give you a pa_timing_info structure
+ * that contains everything that is known about buffers, transport delays
+ * and the backend active in the server.
+ *
+ * If a more simplistic interface is prefered, you can call
+ * pa_stream_get_time() or pa_stream_get_latency(). These will do all the
+ * necessary calculations for you.
+ *
+ * The latency information is constantly updated from the server. Be aware
+ * that between updates, old data will be returned. If you specify the flag
+ * PA_STREAM_INTERPOLATE_TIMING when creating the stream, pa_stream_get_time()
+ * and pa_stream_get_latency() will calculate the latency between updates
+ * based on the time elapsed.
+ *
+ * \section flow_sec Overflow and underflow
+ *
+ * Even with the best precautions, buffers will sometime over- or underflow.
+ * To handle this gracefully, the application can be notified when this
+ * happens. Callbacks are registered using pa_stream_set_overflow_callback()
+ * and pa_stream_set_underflow_callback().
+ *
+ * \section disc_sec Disconnecting
+ *
+ * When a stream has served is purpose it must be disconnected with
+ * pa_stream_disconnect(). If you only unreference it, then it will live on
+ * and eat resources both locally and on the server until you disconnect the
+ * context.
+ */
+
 /** \file
  * Audio streams for input, output and sample upload */
 

src/polyp/subscribe.h

@@ -28,11 +28,22 @@
 #include <polyp/context.h>
 #include <polyp/cdecl.h>
 
+/** \page subscribe Event subscription
+ *
+ * \section overv_sec Overview
+ *
+ * The application can be notified, asynchronously, whenever the internal
+ * layout of the server changes. Possible notifications are desribed in the
+ * \ref pa_subscription_event_type and \ref pa_subscription_mask
+ * enumerations.
+ *
+ * The application sets the notification mask using pa_context_subscribe()
+ * and the function that will be called whenever a notification occurs using
+ * pa_context_set_subscribe_callback().
+ */
+
 /** \file
- * Daemon introspection event subscription subsystem. Use this
+ * Daemon introspection event subscription subsystem. */
- * to be notified whenever the internal layout of daemon changes:
- * i.e. entities such as sinks or sources are create, removed or
- * modified. */
 
 PA_C_DECL_BEGIN
 

src/polyp/volume.h

@@ -26,6 +26,59 @@
 #include <polyp/cdecl.h>
 #include <polyp/sample.h>
 
+/** \page volume Volume control
+ *
+ * \section overv_sec Overview
+ *
+ * Sinks, sources, sink inputs and samples can all have their own volumes.
+ * To deal with these, The Polypaudio libray contains a number of functions
+ * that ease handling.
+ *
+ * The basic volume type in Polypaudio is the \ref pa_volume_t type. Most of
+ * the time, applications will use the aggregated pa_cvolume structure that
+ * can store the volume of all channels at once.
+ *
+ * Volumes commonly span between muted (0%), and normal (100%). It is possible
+ * to set volumes to higher than 100%, but clipping might occur.
+ *
+ * \section calc_sec Calculations
+ *
+ * The volumes in Polypaudio are logarithmic in nature and applications
+ * shouldn't perform calculations with them directly. Instead, they should
+ * be converted to and from either dB or a linear scale:
+ *
+ * \li dB - pa_sw_volume_from_dB() / pa_sw_volume_to_dB()
+ * \li Linear - pa_sw_volume_from_linear() / pa_sw_volume_to_linear()
+ *
+ * For simple multiplication, pa_sw_volume_multiply() and
+ * pa_sw_cvolume_multiply() can be used.
+ *
+ * Calculations can only be reliably be performed on software volumes as
+ * it is commonly unknown what scale hardware volumes use.
+ *
+ * \section conv_sec Convenience functions
+ *
+ * To handle the pa_cvolume structure, the Polypaudio library provides a
+ * number of convenienc functions:
+ *
+ * \li pa_cvolume_valid() - Tests if a pa_cvolume structure is valid.
+ * \li pa_cvolume_equal() - Tests if two pa_cvolume structures are identical.
+ * \li pa_cvolume_channels_equal_to() - Tests if all channels of a pa_cvolume
+ *                             structure have a given volume.
+ * \li pa_cvolume_is_muted() - Tests if all channels of a pa_cvolume
+ *                             structure are muted.
+ * \li pa_cvolume_is_norm() - Tests if all channels of a pa_cvolume structure
+ *                            are at a normal volume.
+ * \li pa_cvolume_set() - Set all channels of a pa_cvolume structure to a
+ *                        certain volume.
+ * \li pa_cvolume_reset() - Set all channels of a pa_cvolume structure to a
+ *                          normal volume.
+ * \li pa_cvolume_mute() - Set all channels of a pa_cvolume structure to a
+ *                         muted volume.
+ * \li pa_cvolume_avg() - Return the average volume of all channels.
+ * \li pa_cvolume_snprint() - Pretty print a pa_cvolume structure.
+ */
+
 /** \file
  * Constants and routines for volume handling */