From ceb09d8ae9bd11380ed3dc7d28054812ff0a0f04 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 13 Apr 2006 00:56:10 +0000 Subject: Documentation updates git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@696 fefdeb5f-60dc-0310-8127-8f9354f1896f --- src/polyp/channelmap.h | 4 +-- src/polyp/context.h | 6 ++-- src/polyp/mainloop.h | 4 +-- src/polyp/sample.h | 2 +- src/polyp/simple.h | 4 +-- src/polyp/stream.h | 75 +++++++++++++++++++++++++++++++++++++++++--------- src/polyp/volume.h | 10 +++++-- 7 files changed, 80 insertions(+), 25 deletions(-) (limited to 'src/polyp') diff --git a/src/polyp/channelmap.h b/src/polyp/channelmap.h index c74f2ceb..99020583 100644 --- a/src/polyp/channelmap.h +++ b/src/polyp/channelmap.h @@ -30,8 +30,8 @@ * \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. + * specific speaker position. This relieves applications of having to + * make sure their channel order is identical to the final output. * * \section init_sec Initialisation * diff --git a/src/polyp/context.h b/src/polyp/context.h index 460034c1..84830811 100644 --- a/src/polyp/context.h +++ b/src/polyp/context.h @@ -48,7 +48,7 @@ * 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 + * To actually be able to use these functions, an implementation needs to * 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. @@ -88,11 +88,11 @@ * channel. * * There is no need for more than one context per application, unless - * connections to multiple servers is needed. + * connections to multiple servers are needed. * * \subsection ops_subsec Operations * - * All operations on the context is performed asynchronously. I.e. the + * All operations on the context are 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. diff --git a/src/polyp/mainloop.h b/src/polyp/mainloop.h index 82d1adc4..6fb2a96c 100644 --- a/src/polyp/mainloop.h +++ b/src/polyp/mainloop.h @@ -45,10 +45,10 @@ PA_C_DECL_BEGIN * consists of three steps that repeat during the application's entire * lifetime: * - * -# Prepare - Dispatch deferred events, build a list of file descriptors + * -# Prepare - 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. + * -# Dispatch - Dispatch any events 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 diff --git a/src/polyp/sample.h b/src/polyp/sample.h index 284b428b..0706be5a 100644 --- a/src/polyp/sample.h +++ b/src/polyp/sample.h @@ -99,7 +99,7 @@ PA_C_DECL_BEGIN -/** Maximum allowed channels */ +/** Maximum number of allowed channels */ #define PA_CHANNELS_MAX 16 /** Sample format */ diff --git a/src/polyp/simple.h b/src/polyp/simple.h index d2adde02..9066826b 100644 --- a/src/polyp/simple.h +++ b/src/polyp/simple.h @@ -47,7 +47,7 @@ * pa_simple *s; * pa_sample_spec ss; * - * ss.format = S16_NE; + * ss.format = PA_SAMPLE_S16_NE; * ss.channels = 2; * ss.rate = 44100; * @@ -70,7 +70,7 @@ * 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. + * and pa_simple_write(). Note that these operations always block. * * \section ctrl_sec Buffer control * diff --git a/src/polyp/stream.h b/src/polyp/stream.h index bb5aa764..6367e868 100644 --- a/src/polyp/stream.h +++ b/src/polyp/stream.h @@ -69,7 +69,7 @@ * * \subsection bufattr_subsec Buffer attributes * - * Playback and record streams always have a buffer as part of the data flow. + * 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 overflows/underruns. * @@ -133,33 +133,82 @@ * 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. + * 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. + * This structure is updated every time a + * pa_stream_update_timing_info() operation is executed. (i.e. before + * the first call to this function the timing information structure is + * not available!) Since it is a lot of work to keep this structure + * up-to-date manually, Polypaudio can do that automatically for you: + * if PA_STREAM_AUTO_TIMING_UPDATE is passed when connecting the + * stream Polypaudio will automatically update the structure every + * 100ms and every time a function is called that might invalidate the + * previously known timing data (such as pa_stream_write() or + * pa_stream_flush()). Please note however, that there always is a + * short time window when the data in the timing information structure + * is out-of-date. Polypaudio tries to mark these situations by + * setting the write_index_corrupt and read_index_corrupt fields + * accordingly. * - * 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. + * The raw timing data in the pa_timing_info structure is usually hard + * to deal with. Therefore a more simplistic 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 + * that you write now takes to be played by the hardware. * + * Since updating the timing info structure usually requires a full + * round trip and some applications monitor the timing very often + * Polypaudio offers a timing interpolation system. If + * PA_STREAM_INTERPOLATE_TIMING is passed when connecting the stream, + * pa_stream_get_time() and pa_stream_get_latency() will try to + * interpolate the current playback time/latency by estimating the + * number of samples that have been played back by the hardware since + * the last regular timing update. It is espcially useful to combine + * this option with PA_STREAM_AUTO_TIMING_UPDATE, which will enable + * you to monitor the current playback time/latency very precisely + * without requiring a network round trip every time. + * * \section flow_sec Overflow and underflow * - * Even with the best precautions, buffers will sometime over- or 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 sync_streams Sychronizing Multiple Playback Streams. + * + * Polypaudio allows applications to fully synchronize multiple playback + * streams that are connected to the same output device. That means + * the streams will always be played back sample-by-sample + * synchronously. If stream operations like pa_stream_cork() are + * issued on one of the synchronized streams, they are simultaneously + * issued on the others. + * + * To synchronize a stream to another, just pass the "master" stream + * as last argument to pa_stream_connect_playack(). To make sure that + * the freshly created stream doesn't start playback right-away, make + * sure to pass PA_STREAM_START_CORKED and - after all streams have + * been created - uncork them all with a single call to + * pa_stream_cork() for the master stream. + * + * To make sure that a particular stream doesn't stop to play when a + * server side buffer underrun happens on it while the other + * synchronized streams continue playing and hence deviate you need to + * pass a "prebuf" pa_buffer_attr of 0 when connecting it. + * + * \section seek_modes Seeking in the Playback Buffer + * + * T.B.D * \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 diff --git a/src/polyp/volume.h b/src/polyp/volume.h index 181784f4..a72069eb 100644 --- a/src/polyp/volume.h +++ b/src/polyp/volume.h @@ -53,8 +53,14 @@ * 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. + * Calculations can only be reliably performed on software volumes + * as it is commonly unknown what scale hardware volumes relate to. + * + * The functions described above are only valid when used with + * software volumes. Hence it is usually a better idea to treat all + * volume values as opaque with a range from PA_VOLUME_MUTE (0%) to + * PA_VOLUME_NORM (100%) and to refrain from any calculations with + * them. * * \section conv_sec Convenience functions * -- cgit