From a6ce5c4b1d82870f5db7063680698cebb4ffe156 Mon Sep 17 00:00:00 2001 From: Pierre Ossman Date: Sun, 9 Apr 2006 19:31:09 +0000 Subject: 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 | 34 +++++++++ src/polyp/context.h | 116 ++++++++++++++++++++++++++--- src/polyp/glib-mainloop.h | 11 +++ src/polyp/introspect.h | 184 ++++++++++++++++++++++++++++++++++++++++++---- src/polyp/mainloop.h | 35 +++++++++ src/polyp/polypaudio.h | 52 +++++++------ src/polyp/sample.h | 66 +++++++++++++++++ src/polyp/scache.h | 43 +++++++++++ src/polyp/simple.h | 65 +++++++++++++++- src/polyp/stream.h | 131 +++++++++++++++++++++++++++++++++ src/polyp/subscribe.h | 19 ++++- src/polyp/volume.h | 53 +++++++++++++ 12 files changed, 757 insertions(+), 52 deletions(-) (limited to 'src/polyp') diff --git a/src/polyp/channelmap.h b/src/polyp/channelmap.h index dd508abe..c74f2ceb 100644 --- a/src/polyp/channelmap.h +++ b/src/polyp/channelmap.h @@ -25,6 +25,40 @@ #include #include +/** \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 */ diff --git a/src/polyp/context.h b/src/polyp/context.h index 89febe92..460034c1 100644 --- a/src/polyp/context.h +++ b/src/polyp/context.h @@ -28,18 +28,116 @@ #include #include +/** \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 - * 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(). */ + * server using its native protocol. */ /** \example pacat.c * A playback and recording tool using the asynchronous API */ diff --git a/src/polyp/glib-mainloop.h b/src/polyp/glib-mainloop.h index b7717685..bc66409b 100644 --- a/src/polyp/glib-mainloop.h +++ b/src/polyp/glib-mainloop.h @@ -27,6 +27,17 @@ #include #include +/** \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 */ diff --git a/src/polyp/introspect.h b/src/polyp/introspect.h index fb05cfb9..5d567836 100644 --- a/src/polyp/introspect.h +++ b/src/polyp/introspect.h @@ -30,22 +30,176 @@ #include #include +/** \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 - * 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. */ + * Routines for daemon introspection. + */ 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); diff --git a/src/polyp/mainloop.h b/src/polyp/mainloop.h index d0a40914..c06b47d0 100644 --- a/src/polyp/mainloop.h +++ b/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() diff --git a/src/polyp/polypaudio.h b/src/polyp/polypaudio.h index b70b8d70..af80f9ea 100644 --- a/src/polyp/polypaudio.h +++ b/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 - * based style or want to use advanced features of the polypaudio - * API. A good starting point is \ref context.h + * Use this if you develop your programs in asynchronous, event loop + * based style or if you want to use the advanced features of the + * polypaudio API. A guide can be found in \subpage async. * - * The asynchronous API relies on an abstract main loop API that is - * 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 + * \section thread_sec Threads + * + * The polypaudio client libraries are not designed to be used in a + * heavily threaded environment. They are however designed to be reentrant + * safe. * - * UNIX signals may be hooked to a main loop using the functions from - * \ref mainloop-signal.h + * 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 - * asynchronous API use "polyplib" as pkg-config file. GLIB main loop - * support is available as "glib-mainloop". The simple - * synchronous API is available as "simple". + * The polypaudio libraries provide pkg-config snippets for the different + * modules: + * + * \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 diff --git a/src/polyp/sample.h b/src/polyp/sample.h index db4c6c70..a7abdc3e 100644 --- a/src/polyp/sample.h +++ b/src/polyp/sample.h @@ -28,6 +28,72 @@ #include +/** \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 */ diff --git a/src/polyp/scache.h b/src/polyp/scache.h index cdb47cab..a6b312f5 100644 --- a/src/polyp/scache.h +++ b/src/polyp/scache.h @@ -28,6 +28,49 @@ #include #include +/** \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 */ diff --git a/src/polyp/simple.h b/src/polyp/simple.h index 1a139005..d2adde02 100644 --- a/src/polyp/simple.h +++ b/src/polyp/simple.h @@ -28,9 +28,72 @@ #include #include +/** \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 diff --git a/src/polyp/stream.h b/src/polyp/stream.h index ce041986..bb5aa764 100644 --- a/src/polyp/stream.h +++ b/src/polyp/stream.h @@ -31,6 +31,137 @@ #include #include +/** \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 */ diff --git a/src/polyp/subscribe.h b/src/polyp/subscribe.h index 5301739a..75b4696f 100644 --- a/src/polyp/subscribe.h +++ b/src/polyp/subscribe.h @@ -28,11 +28,22 @@ #include #include +/** \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 - * to be notified whenever the internal layout of daemon changes: - * i.e. entities such as sinks or sources are create, removed or - * modified. */ + * Daemon introspection event subscription subsystem. */ PA_C_DECL_BEGIN diff --git a/src/polyp/volume.h b/src/polyp/volume.h index d1e858c4..181784f4 100644 --- a/src/polyp/volume.h +++ b/src/polyp/volume.h @@ -26,6 +26,59 @@ #include #include +/** \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 */ -- cgit