[polypaudio-commits] r696 - in /trunk/src/polyp: channelmap.h context.h mainloop.h sample.h simple.h stream.h volume.h
svnmailer-noreply at 0pointer.de
svnmailer-noreply at 0pointer.de
Wed Apr 12 17:56:11 PDT 2006
Author: lennart
Date: Thu Apr 13 02:56:10 2006
New Revision: 696
URL: http://0pointer.de/cgi-bin/viewcvs.cgi?rev=696&root=polypaudio&view=rev
Log:
Documentation updates
Modified:
trunk/src/polyp/channelmap.h
trunk/src/polyp/context.h
trunk/src/polyp/mainloop.h
trunk/src/polyp/sample.h
trunk/src/polyp/simple.h
trunk/src/polyp/stream.h
trunk/src/polyp/volume.h
Modified: trunk/src/polyp/channelmap.h
URL: http://0pointer.de/cgi-bin/viewcvs.cgi/trunk/src/polyp/channelmap.h?rev=696&root=polypaudio&r1=695&r2=696&view=diff
==============================================================================
--- trunk/src/polyp/channelmap.h (original)
+++ trunk/src/polyp/channelmap.h Thu Apr 13 02:56:10 2006
@@ -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
*
Modified: trunk/src/polyp/context.h
URL: http://0pointer.de/cgi-bin/viewcvs.cgi/trunk/src/polyp/context.h?rev=696&root=polypaudio&r1=695&r2=696&view=diff
==============================================================================
--- trunk/src/polyp/context.h (original)
+++ trunk/src/polyp/context.h Thu Apr 13 02:56:10 2006
@@ -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.
Modified: trunk/src/polyp/mainloop.h
URL: http://0pointer.de/cgi-bin/viewcvs.cgi/trunk/src/polyp/mainloop.h?rev=696&root=polypaudio&r1=695&r2=696&view=diff
==============================================================================
--- trunk/src/polyp/mainloop.h (original)
+++ trunk/src/polyp/mainloop.h Thu Apr 13 02:56:10 2006
@@ -45,10 +45,10 @@
* 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
Modified: trunk/src/polyp/sample.h
URL: http://0pointer.de/cgi-bin/viewcvs.cgi/trunk/src/polyp/sample.h?rev=696&root=polypaudio&r1=695&r2=696&view=diff
==============================================================================
--- trunk/src/polyp/sample.h (original)
+++ trunk/src/polyp/sample.h Thu Apr 13 02:56:10 2006
@@ -99,7 +99,7 @@
PA_C_DECL_BEGIN
-/** Maximum allowed channels */
+/** Maximum number of allowed channels */
#define PA_CHANNELS_MAX 16
/** Sample format */
Modified: trunk/src/polyp/simple.h
URL: http://0pointer.de/cgi-bin/viewcvs.cgi/trunk/src/polyp/simple.h?rev=696&root=polypaudio&r1=695&r2=696&view=diff
==============================================================================
--- trunk/src/polyp/simple.h (original)
+++ trunk/src/polyp/simple.h Thu Apr 13 02:56:10 2006
@@ -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
*
Modified: trunk/src/polyp/stream.h
URL: http://0pointer.de/cgi-bin/viewcvs.cgi/trunk/src/polyp/stream.h?rev=696&root=polypaudio&r1=695&r2=696&view=diff
==============================================================================
--- trunk/src/polyp/stream.h (original)
+++ trunk/src/polyp/stream.h Thu Apr 13 02:56:10 2006
@@ -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.
- *
- * 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.
- *
+ * 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.
+ *
+ * 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 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
Modified: trunk/src/polyp/volume.h
URL: http://0pointer.de/cgi-bin/viewcvs.cgi/trunk/src/polyp/volume.h?rev=696&root=polypaudio&r1=695&r2=696&view=diff
==============================================================================
--- trunk/src/polyp/volume.h (original)
+++ trunk/src/polyp/volume.h Thu Apr 13 02:56:10 2006
@@ -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
*
More information about the pulseaudio-commits
mailing list