[xiph-commits] r17011 - in trunk/ao: doc src/plugins/macosx
xiphmont at svn.xiph.org
xiphmont at svn.xiph.org
Tue Mar 23 23:48:31 PDT 2010
Author: xiphmont
Date: 2010-03-23 23:48:31 -0700 (Tue, 23 Mar 2010)
New Revision: 17011
Added:
trunk/ao/doc/ao_append_global_option.html
Modified:
trunk/ao/doc/ao_plugin_device_init.html
trunk/ao/doc/ao_plugin_open.html
trunk/ao/doc/ao_sample_format.html
trunk/ao/doc/config.html
trunk/ao/doc/drivers.html
trunk/ao/doc/index.html
trunk/ao/doc/libao-api.html
trunk/ao/doc/plugin-overview.html
trunk/ao/src/plugins/macosx/ao_macosx.c
Log:
Doc updates
Shorten macosx_auhal driver name back to macosx
Added: trunk/ao/doc/ao_append_global_option.html
===================================================================
--- trunk/ao/doc/ao_append_global_option.html (rev 0)
+++ trunk/ao/doc/ao_append_global_option.html 2010-03-24 06:48:31 UTC (rev 17011)
@@ -0,0 +1,67 @@
+<html>
+
+<head>
+<title>libao - function - ao_append_global_option</title>
+<link rel=stylesheet href="style.css" type="text/css">
+</head>
+
+<body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
+<table border=0 width=100%>
+<tr>
+<td><p class=tiny>libao documentation</p></td>
+<td align=right><p class=tiny>libao version 1.0.0 - 20100324</p></td>
+</tr>
+</table>
+
+<h1>ao_append_option</h1>
+
+<p><i>declared in "ao/ao.h";</i></p>
+
+<p>Append a key-value pair to the internal linked list of global
+options obeyed by libao itself, as well as passed to any driver in
+use. The key and value strings are duplicated into newly allocated
+memory, so the calling function retains ownership of the string
+parameters.
+
+<br><br>
+<table border=0 color=black cellspacing=0 cellpadding=7>
+<tr bgcolor=#cccccc>
+ <td>
+<pre><b>
+int ao_append_global_option(const char *key, const char *value);
+</b></pre>
+ </td>
+</tr>
+</table>
+
+<h3>Parameters</h3>
+<dl>
+<dt><i>key</i></dt>
+<dd>A string holding the option key.</dd>
+<dt><i>num_bytes</i></dt>
+<dd>A string holding the option value.</dd>
+</dl>
+
+<h3>Return Values</h3>
+<blockquote>
+<li>1 indicates success.</li>
+
+<li>0 indicates memory allocation failure.</li>
+</blockquote>
+<p>
+
+<br><br>
+<hr noshade>
+<table border=0 width=100%>
+<tr valign=top>
+<td><p class=tiny>copyright © 2001-2003 Stan Seibert, 2010 Monty</p></td>
+<td align=right><p class=tiny><a href="http://www.xiph.org/">xiph.org</a><br><a href="mailto:monty at xiph.org">monty at xiph.org</a></p></td>
+</tr><tr>
+<td><p class=tiny>libao documentation</p></td>
+<td align=right><p class=tiny>libao version 1.0.0 - 20100324</p></td>
+</tr>
+</table>
+
+</body>
+
+</html>
Modified: trunk/ao/doc/ao_plugin_device_init.html
===================================================================
--- trunk/ao/doc/ao_plugin_device_init.html 2010-03-24 06:05:54 UTC (rev 17010)
+++ trunk/ao/doc/ao_plugin_device_init.html 2010-03-24 06:48:31 UTC (rev 17011)
@@ -9,7 +9,7 @@
<table border=0 width=100%>
<tr>
<td><p class=tiny>libao documentation</p></td>
-<td align=right><p class=tiny>libao version 0.9.0 - 20100124</p></td>
+<td align=right><p class=tiny>libao version 1.0.0 - 20100324</p></td>
</tr>
</table>
@@ -22,6 +22,38 @@
be opened until <a href="ao_plugin_open.html">ao_plugin_open()</a> is
called.
+<p>Drivers that wish to support automatic surround channel mapping should set <tt>device->output_matrix_order</tt> to one of:
+<ul>
+
+<li>AO_OUTPUT_MATRIX_FIXED - The audio driver outputs a fixed channel
+order that is always the same for a given number of channels and can't
+be changed. One example is ALSA where to play to the side right
+speaker, it is necessary to open eight channels and write to side
+right as channel eight, even if the other seven channels are unused.
+
+<li>AO_OUTPUT_MATRIX_COLLAPSIBLE - The audio driver outputs a fixed
+channel order that is always the same, but unused channels are not
+sent. In such a driver with the channel order 'L,R,C,LFE,BL,BR', we
+can write to the two rear speakers without opening six channels but
+the rear speakers must still be in the order 'BL,BR'. Such drivers
+usually use a bitmap to represent the channels present in the output.
+Examples are wav, wmm and macosx.
+
+<li>AO_OUTPUT_MATRIX_PERMUTABLE - Channels may be arranged in any
+order. An example of such a driver is pulse.
+</ul>
+
+In addition, a driver may set <tt>device->output_matrix</tt> to the
+list of possible output channels in order. Note that even
+AO_OUTPUT_MATRIX_PERMUTABLE drivers usually have a fixed numbering
+scheme for channels even if the channels may be sent in any order. A
+driver that is unable to set an output matrix without inspecting the
+input sample format (for example, the roar driver), may set
+<tt>device->output_matrix_order</tt> to
+<tt>AO_OUTPUT_MATRIX_FIXED</tt> and delay channel mapping
+initialization until <a
+href="ao_plugin_open.html">ao_plugin_open()</a>.
+
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
@@ -58,7 +90,7 @@
<td align=right><p class=tiny><a href="http://www.xiph.org/">xiph.org</a><br><a href="mailto:monty at xiph.org">monty at xiph.org</a></p></td>
</tr><tr>
<td><p class=tiny>libao documentation</p></td>
-<td align=right><p class=tiny>libao version 0.9.0 - 20100124</p></td>
+<td align=right><p class=tiny>libao version 1.0.0 - 20100324</p></td>
</tr>
</table>
Modified: trunk/ao/doc/ao_plugin_open.html
===================================================================
--- trunk/ao/doc/ao_plugin_open.html 2010-03-24 06:05:54 UTC (rev 17010)
+++ trunk/ao/doc/ao_plugin_open.html 2010-03-24 06:48:31 UTC (rev 17011)
@@ -9,7 +9,7 @@
<table border=0 width=100%>
<tr>
<td><p class=tiny>libao documentation</p></td>
-<td align=right><p class=tiny>libao version 0.9.0 - 20100124</p></td>
+<td align=right><p class=tiny>libao version 1.0.0 - 20100324</p></td>
</tr>
</table>
@@ -23,6 +23,22 @@
file output driver, the file itself will have be already opened and a
pointer to a <tt>FILE</tt> structure stored in <tt>device->file</tt>.
+<p>If the plugin wishes to support automatic channel mapping, but it
+was not possible to set <tt>device->output_matrix</tt> in <a
+href="ao_plugin_device_init.html">ao_plugin_device_init()</a>, the
+plugin should now set <tt>device->inter_matrix</tt> to the channel
+ordering that will be expected for buffers submitted to <a
+href="ao_plugin_play.html">ao_plugin_play()</a>.
+
+<p>Plugins should use <tt>device->output_channels</tt> to determine
+the number of output channels to configure, not
+<tt>format->channels</tt>. <tt>device->output_channels</tt> is the
+number of channels libao will be submitting upon each call to <a
+href="ao_plugin_play.html">ao_plugin_play()</a>. A plugin may alter
+the value of <tt>device->output_channels</tt> to demand a different
+number of channels if necessary (such as if a plugin is manufacturing
+a channel mapping manually).
+
<br><br>
<table border=0 color=black cellspacing=0 cellpadding=7>
<tr bgcolor=#cccccc>
@@ -40,8 +56,14 @@
<dd>Pointer to pre-allocated device structure. The plugin should
set its desired byte format in <tt>device->driver_byte_format</tt>.</dd>
<dt><i>format</i></dt>
-<dd>Output device sample format. <tt>format->byte_format</tt> should be
-ignored as it is relevant only to the library core.</dd>
+
+<dd>Output device sample format. <tt>format->byte_format</tt> should
+be ignored as it is relevant only to the library core.
+<tt>format->channels</tt> is relevant only if a plugin is constructing
+a channel mapping manually; otherwise <tt>device->output</tt> should
+be used as it is the actual number of channels that will be sent to <a
+href="ao_plugin_play.html">ao_plugin_play()</a>.</dd>
+
</dl>
<h3>Return Values</h3>
@@ -62,7 +84,7 @@
<td align=right><p class=tiny><a href="http://www.xiph.org/">xiph.org</a><br><a href="mailto:monty at xiph.org">monty at xiph.org</a></p></td>
</tr><tr>
<td><p class=tiny>libao documentation</p></td>
-<td align=right><p class=tiny>libao version 0.9.0 - 20100124</p></td>
+<td align=right><p class=tiny>libao version 1.0.0 - 20100324</p></td>
</tr>
</table>
Modified: trunk/ao/doc/ao_sample_format.html
===================================================================
--- trunk/ao/doc/ao_sample_format.html 2010-03-24 06:05:54 UTC (rev 17010)
+++ trunk/ao/doc/ao_sample_format.html 2010-03-24 06:48:31 UTC (rev 17011)
@@ -9,7 +9,7 @@
<table border=0 width=100%>
<tr>
<td><p class=tiny>libao documentation</p></td>
-<td align=right><p class=tiny>libao version 0.9.0 - 20100124</p></td>
+<td align=right><p class=tiny>libao version 1.0.0 - 20100324</p></td>
</tr>
</table>
@@ -62,7 +62,7 @@
<li>SR - Side Right speaker, located directly to the listener's right side. The Side Right speaker is also referred to as 'Right Surround Direct' (primarily by Apple) or 'Surround Right' (primarily by Dolby) </li>
<li>LFE - Low Frequency Effect (subwoofer) channel. This is channel is usually lowpassed and meant only for bass, though in some recent formats it is a discrete, full-range channel. Microsoft calls this the 'Low Frequency' channel.
<li>A1, A2, A3, A4 - 'auxiliary' channels, not mapped to a location. Intended for driver-specific use.</li>
-<li>U - Unused channel, to be dropped in the driver and not output to any speaker.</li>
+<li>X - Unused/Invalid channel, to be dropped in the driver and not output to any speaker.</li>
</ul>
<p><i>Note that the 'surround' speakers referred to in other systems
@@ -88,7 +88,7 @@
channel matrix (there are a few exceptions like Vorbis I, where the
number of channels always maps to a specific order); the above
examples cannot be blindly applied to a given file type and number of
-channels. The mapping must usually be read from the input.
+channels. The mapping must usually be read or intuited from the input.
</dd>
</dl>
@@ -102,7 +102,7 @@
<td align=right><p class=tiny><a href="http://www.xiph.org/">xiph.org</a><br><a href="mailto:monty at xiph.org">monty at xiph.org</a></p></td>
</tr><tr>
<td><p class=tiny>libao documentation</p></td>
-<td align=right><p class=tiny>libao version 0.9.0 - 20100124</p></td>
+<td align=right><p class=tiny>libao version 1.0.0 - 20100324</p></td>
</tr>
</table>
Modified: trunk/ao/doc/config.html
===================================================================
--- trunk/ao/doc/config.html 2010-03-24 06:05:54 UTC (rev 17010)
+++ trunk/ao/doc/config.html 2010-03-24 06:48:31 UTC (rev 17011)
@@ -9,7 +9,7 @@
<table border=0 width=100%>
<tr>
<td><p class=tiny>libao documentation</p></td>
-<td align=right><p class=tiny>libao version 0.9.0 - 20100124</p></td>
+<td align=right><p class=tiny>libao version 1.0.0 - 20100324</p></td>
</tr>
</table>
@@ -31,14 +31,28 @@
</pre>
There can be no extra spaces anywhere on the line. Comment lines begin with a <tt>#</tt> symbol.
-<h2>Options</h2>
+<h2>AO Options</h2>
<dl>
<dt><i>default_driver</i></dt>
<dd>Set this equal to the short name of the driver you want the system to use by default. If this is not specified in any of the configuration files, the library will try to guess an appropriate driver to use.
+<dt><i>debug</i> (Value optional/ignored)</dt>
+<dd>Sets all the drivers as well as AO itself into debugging output mode. Unlike passing the debug option to a driver, <tt>debug</tt> will also print debugging information from driver loading and testing.
</dd>
+<dt><i>quiet</i> (Value optional/ignored)</dt>
+<dd>Sets all the drivers as well as AO itself into silent mode. Errors will return only error codes; neither ao nor the drivers will print any output whatsoever to stderr.
+</dd>
+<dt><i>verbose</i> (Value optional/ignored)</dt>
+<dd>Sets all the drivers as well as AO itself into verbose mode.
+</dd>
+
</dl>
+<h2>Driver Options</h2>
+
+<a href="drivers.html">Driver options</a> may be set in the configuration files using <tt>option=value</tt> pairs, just as they would be set by passing <a href="ao_option.html">options</a> to <a href="ao_open_live.html">ao_open_live()</a> or <a href="ao_open_file.html">ao_open_file()</a>. Options passed to <a href="ao_open_live.html">ao_open_live()</a> or <a href="ao_open_file.html">ao_open_file()</a> take precedence over options specified in a configuration file. Options specified in a configuration file will be passed to whatever driver is eventually opened; they cannot be set specific to a single driver.
+<p>
+
<br><br>
<hr noshade>
<table border=0 width=100%>
@@ -47,7 +61,7 @@
<td align=right><p class=tiny><a href="http://www.xiph.org/">xiph.org</a><br><a href="mailto:monty at xiph.org">monty at xiph.org</a></p></td>
</tr><tr>
<td><p class=tiny>libao documentation</p></td>
-<td align=right><p class=tiny>libao version 0.9.0 - 20100124</p></td>
+<td align=right><p class=tiny>libao version 1.0.0 - 20100324</p></td>
</tr>
</table>
Modified: trunk/ao/doc/drivers.html
===================================================================
--- trunk/ao/doc/drivers.html 2010-03-24 06:05:54 UTC (rev 17010)
+++ trunk/ao/doc/drivers.html 2010-03-24 06:48:31 UTC (rev 17011)
@@ -14,7 +14,7 @@
</table>
<h1>libao Drivers</h1>
-
+
<p>
Libao supports both <i>live</i> output drivers and <i>file</i> output
drivers. Live output drivers send audio data to sound cards and sound
@@ -24,18 +24,51 @@
using, but otherwise live and file drivers are treated identically in
libao.
+<p>Driver options may be passed to the drivers via the
+<tt>*options</tt> argument to <a
+href="ao_open_live.html">ao_open_live()</a> and <a
+href="ao_open_file.html">ao_open_file()</a>, or they may be set in the
+<a href="config.html">configuration file</a> as <tt>name=value</tt>
+pairs.
+
+<h2>Options understood by all Drivers</h2>
+<ul>
+
+<li>"debug" - (value not required) Requests driver print detailed
+debugging information.
+
+<li>"matrix" - Set an output channel mapping similar to the use of the
+<i>matrix</i> field in <a
+href="ao_sample_format.html">ao_sample_format</a>. The specified
+matrix overrides the backend's native channel ordering/numbering. The
+channel numbering used by the driver does not necessarily reflect the
+physical ordering; for example, the fourth PulseAudio channel is
+always 'Center' by default whether the channel physically exists or not.
+
+<li>"quiet" - (value not required) Requests the driver print no output
+whatsoever, even in the event of error.
+
+<li>"verbose" - (value not required) Requests that the driver print
+more detailed information concerning normal operation.
+</ul>
+
<h2>Live Output Drivers</h2>
-<h3>null</h3>
+<h3>aixs</h3>
-Null driver. This is just a test device which does not write the
-audio data anywhere.
+IBM AIX sound driver. According to the author, "tested on AIX 5.1 with
+the Crystal chipsets only (found as internal audio in the 7043-140 and
+on the MCA adapter DFE5 (7-6)), but it should work with other AIX
+releases and the ACPA also."
<p>
<b>Option keys:</b>
<ul>
-<li>"debug" - Print the number of bytes written to the device to stderr
-when the device is closed. The option value is ignored.
+<li>"dev" - The audio device for the sound card. By default, the
+driver tries "/dev/baud0/1" (device for MCA machines with the Crystal
+chipset). Other possible devices are "/dev/paud0/1" for PCI machines
+with the Crystal chipset, and "/dev/acpa0/1" for MCA machines with the
+ACPA.
</ul>
<p>
@@ -43,39 +76,47 @@
<h3>alsa</h3>
-Advanced Linux Sound Architecture. This driver borrows some code from
-Jaroslav Kysela's <perex at suse.cz> GPLed aplay that is included with
-the alsa-util distribution. It defaults to device 0 on card 0.
-Because of the way ALSA reads data, this driver packs sound from
-successive calls into a fixed size buffer (defaults to 32kB) and sends
-it to the card. Note that this driver only works with ALSA 0.5.x.
-You should use the <tt>alsa09</tt> driver for the ALSA 0.9.x or 1.0.x
-series.
+Advanced Linux Sound Architecture (API versions 0.9.x/1.x.x; earlier
+API versions are now deprecated).
<p>
<b>Option keys:</b>
<ul>
-<li>"card" - Sound card number.
-<li>"dev" - Device number on sound card.
-<li>"buf_size" - Override the internal buffer size (in bytes).
-Experiment with this if the sound skips. Default is 32768.
+
+<li>"buffer_time" - Override the default hardware buffer size (in
+milliseconds).
+
+<li>"dev" - ALSA device label to use. Examples include "hw:0" for the
+first soundcard and "hw:1" for the second. The alsa driver normally
+chooses one of "surround71", "surround51", "surround40" or "default"
+automatically depending on number of output channels.
+
+<li>"period_time" - Override the default hardware period size (in
+microseconds).
+
+<li>"use_mmap" - set to "yes" or "no" to override the compiled-in
+default to use or not use mmap device access. In
+the past, some buggy alsa drivers have behaved
+better when not using mmap access at the penalty
+of slightly higher CPU usage.
+
</ul>
<p>
<hr width="50%">
-<h3>alsa09</h3>
+<h3>arts</h3>
-Advanced Linux Sound Architecture, version 0.9.x and 1.0.x API. This
-is essentially the alsa driver modified to use the newer API.
+aRts Sound Daemon live output driver.
<p>
<b>Option keys:</b>
<ul>
-<li>"dev" - Device name of sound card. Defaults to "default".
-<li>"buf_time" - Override the hardward buffer size (in milliseconds).
-<li>"period_time" - Override the size of periods ALSA uses.
-<li>"use_mmap" - Set to "1" to enable the use of memory-mapped I/O API.
+
+<li>"multi" - set to "yes" to allow opening the aRts playback device
+for multiply concurrent playback. Although the driver works properly
+in multi mode, it is known to occasionally crash the aRts server
+itself. Default behavior is "no".
</ul>
<p>
@@ -83,9 +124,10 @@
<h3>esd</h3>
-ESounD audio driver. This sound daemon is used on some Linux systems.
-It permits multiple programs to play sound simultaneously and sound to
-be sent to networked computers.
+ESounD audio driver. Although declining in poularity, this sound
+daemon is still used on some Linux systems. It permits multiple
+programs to play sound simultaneously and sound to be sent to
+networked computers.
<p>
<b>Option keys:</b>
@@ -105,15 +147,49 @@
fix it! I don't have access to an IRIX system.)
<p>
-<b>Option keys:</b> None.
+<hr width="50%">
+
+<h3>macosx</h3>
+
+MacOS X AUHAL live output driver. This driver supports MacOS X 10.5
+and later (10.4 and earlier uses an earlier, incompatable interface).
+
<p>
+<b>Option keys:</b>
+<ul>
+<li>"buffer_time" - Set the hardware buffer size to the equivalent of
+value milliseconds.
+</ul>
+<p>
+
<hr width="50%">
+<h3>nas</h3>
+Network Audio System live output driver.
+<p>
+
+<b>Option keys:</b>
+<ul>
+<li>"buf_size" - Set size of audio buffer on server in bytes.
+<li>"host" - Set location of NAS server; See nas(1) for format.
+</ul>
+<p>
+
+<hr width="50%">
+
+<h3>null</h3>
+
+Null driver. This is just a test device which does not write the
+audio data anywhere.
+<p>
+
+<hr width="50%">
+
<h3>oss</h3>
Open Sound System driver. This is the audio system for
-Linux and FreeBSD as well as some other UNIX-like systems.
+older Linux and FreeBSD as well as some other UNIX-like systems.
<p>
<b>Option keys:</b>
@@ -125,6 +201,47 @@
<hr width="50%">
+<h3>pulse</h3>
+
+PulseAudio live audio sound driver. Pulse is a sound server daemon
+used by the modern Gnome desktop on UNIX-like systems.
+
+<p>
+<b>Option keys:</b>
+<ul>
+<li>"server" - Specifies Pulseaudio server to use.
+<li>"sink" - Specifies Pulseaudio sink to use.
+</ul>
+<p>
+
+<hr width="50%">
+
+<h3>roar</h3>
+
+Roar Audio live audio sound driver.
+
+<p>
+<b>Option keys:</b>
+<ul>
+<li>"host" - Specifies Roar server to use.
+</ul>
+<p>
+
+<hr width="50%">
+
+<h3>sndio</h3>
+
+SNDIO is the modern audio interface used by OpenBSD.
+
+<p>
+<b>Option keys:</b>
+<ul>
+<li>"dev" - Specifies audio device to use.
+</ul>
+<p>
+
+<hr width="50%">
+
<h3>sun</h3>
Sun audio driver. This is the audio system for NetBSD, OpenBSD, and
@@ -140,18 +257,15 @@
<hr width="50%">
-<h3>aixs</h3>
+<h3>wmm</h3>
-AIX sound driver. According to the author, "tested on AIX 5.1 with the Crystal chipsets only (found as internal audio in the 7043-140 and on the MCA adapter DFE5 (7-6)), but it should work with other AIX releases and the ACPA also."
+Windows MMSound output driver for Win98 and later.
<p>
<b>Option keys:</b>
<ul>
-<li>"dev" - The audio device for the sound card. By default, the
-driver tries "/dev/baud0/1" (device for MCA machines with the Crystal
-chipset). Other possible devices are "/dev/paud0/1" for PCI machines
-with the Crystal chipset, and "/dev/acpa0/1" for MCA machines with the
-ACPA.
+<li>"dev" - Selects audio device to use for playback by device name.
+<li>"id" - Selects audio device to use for playback by device id (card number).
</ul>
<p>
@@ -166,9 +280,6 @@
which the wav driver cannot do.
<p>
-<b>Option keys:</b> None.
-<p>
-
<hr width="50%">
<h3>raw</h3>
@@ -189,15 +300,12 @@
<h3>wav</h3>
-Windows sound file output. Because of the way WAV files are
+Windows 'WAV' sound file output. Because of the way WAV files are
structured, this driver cannot correct files unless the target file is
seekable. Writing WAVs to stdout will result in broken files. Use
-either the raw or the au driver instead.
+either the raw or the au driver instead.
<p>
-<b>Option keys:</b> None.
-<p>
-
<hr>
<a name="default_driver">
@@ -217,19 +325,32 @@
The ranking system currently used is:
<center>
<table border="1">
- <tr><th>Priority</th><th>Drivers</th> </tr>
- <tr><td>30</td> <td>alsa, alsa09</td> </tr>
- <tr><td>20</td> <td>oss, irix, sun</td> </tr>
- <tr><td>10</td> <td>esd,arts</td> </tr>
+ <tr><th>Priority</th><th>Drivers</th> </tr>
+ <tr><td>50</td> <td>pulse, roar</td> </tr>
+ <tr><td>45</td> <td>arts*</td> </tr>
+ <tr><td>40</td> <td>esd</td> </tr>
+ <tr><td>35</td> <td>alsa</td> </tr>
+ <tr><td>30</td> <td>macosx, sndio </td> </tr>
+ <tr><td>20</td> <td>aixs, oss, irix, sun, wmm</td> </tr>
+ <tr><td>15</td> <td>arts*</td> </tr>
+ <tr><td>10</td> <td>nas</td> </tr>
<tr bgcolor="#888888"><td> 0</td> <td>null, all file output</td></tr>
</table>
</center>
<p>
+<i>*arts priority depends on whether or not the arts install was built
+with <tt>HAVE_ARTS_SUSPENDED</tt>; when present, the default aRts
+priority is 45, else it is 15.</i>
-Clearly, any ranking scheme will fail to make everybody happy. For
+<p>Clearly, any ranking scheme will fail to make everybody happy. For
such cases, the <a href="config.html">configuration files</a> can be
-easily used to define an appropriate default output device
+easily used to define an appropriate default output device.
+<p>Adding <tt>debug</tt> to the libao <a
+href="config.html">configuration file</a> on a line by itself will
+cause libao to print what static and dynamic drivers are available for
+use, as well as print the testing order.
+
<br><br>
<hr noshade>
<table border=0 width=100%>
Modified: trunk/ao/doc/index.html
===================================================================
--- trunk/ao/doc/index.html 2010-03-24 06:05:54 UTC (rev 17010)
+++ trunk/ao/doc/index.html 2010-03-24 06:48:31 UTC (rev 17011)
@@ -9,7 +9,7 @@
<table border=0 width=100%>
<tr>
<td><p class=tiny>libao documentation</p></td>
-<td align=right><p class=tiny>libao version 0.9.0 - 20100124</p></td>
+<td align=right><p class=tiny>libao version 1.0.0 - 20100324</p></td>
</tr>
</table>
@@ -26,9 +26,11 @@
<li>Sun audio system (used in Solaris, OpenBSD, and NetBSD)
<li>aRts (Analog Realtime Synthesizer)
<li>PulseAudio
+ <li>Roar Audio
+ <li>OpenBSD SNDIO
<li>Windows MMSound
<li>IRIX
- <li>MacOSX
+ <li>MacOS X (AU HAL)
<li>NAS
<li>AIX
</ul>
@@ -49,7 +51,7 @@
<td align=right><p class=tiny><a href="http://www.xiph.org/">xiph.org</a><br><a href="mailto:monty at xiph.org">monty at xiph.org</a></p></td>
</tr><tr>
<td><p class=tiny>libao documentation</p></td>
-<td align=right><p class=tiny>libao version 0.9.0 - 20100124</p></td>
+<td align=right><p class=tiny>libao version 1.0.0 - 20100324</p></td>
</tr>
</table>
Modified: trunk/ao/doc/libao-api.html
===================================================================
--- trunk/ao/doc/libao-api.html 2010-03-24 06:05:54 UTC (rev 17010)
+++ trunk/ao/doc/libao-api.html 2010-03-24 06:48:31 UTC (rev 17011)
@@ -9,7 +9,7 @@
<table border=0 width=100%>
<tr>
<td><p class=tiny>libao documentation</p></td>
-<td align=right><p class=tiny>libao version 0.9.0 - 20100124</p></td>
+<td align=right><p class=tiny>libao version 1.0.0 - 20100324</p></td>
</tr>
</table>
@@ -28,6 +28,7 @@
<br>
<b>Device Setup/Playback/Teardown</b><br>
<a href="ao_append_option.html">ao_append_option()</a><br>
+<a href="ao_append_global_option.html">ao_append_global_option()</a><br>
<a href="ao_free_options.html">ao_free_options()</a><br>
<a href="ao_open_live.html">ao_open_live()</a><br>
<a href="ao_open_file.html">ao_open_file()</a><br>
@@ -52,7 +53,7 @@
<td align=right><p class=tiny><a href="http://www.xiph.org/">xiph.org</a><br><a href="mailto:monty at xiph.org">monty at xiph.org</a></p></td>
</tr><tr>
<td><p class=tiny>libao documentation</p></td>
-<td align=right><p class=tiny>libao version 0.9.0 - 20100124</p></td>
+<td align=right><p class=tiny>libao version 1.0.0 - 20100324</p></td>
</tr>
</table>
Modified: trunk/ao/doc/plugin-overview.html
===================================================================
--- trunk/ao/doc/plugin-overview.html 2010-03-24 06:05:54 UTC (rev 17010)
+++ trunk/ao/doc/plugin-overview.html 2010-03-24 06:48:31 UTC (rev 17011)
@@ -9,7 +9,7 @@
<table border=0 width=100%>
<tr>
<td><p class=tiny>libao documentation</p></td>
-<td align=right><p class=tiny>libao version 0.9.0 - 20100124</p></td>
+<td align=right><p class=tiny>libao version 1.0.0 - 20100324</p></td>
</tr>
</table>
@@ -53,14 +53,16 @@
parameter passed to the library by the client application.
<li>Call <a href="ao_plugin_open.html">ao_plugin_open.html</a> to
- open the device for playback.
+ open the device for playback.
</ul>
<li>Each time the client app calls <a
href="ao_play.html">ao_play()</a>, the library will reorder the byte
-format (little-endian vs. big-endian) to match the format requested by
-the plugin. The library will then call <a href="ao_plugin_play.html">ao_plugin_play()</a> for the block of audio data.
+format (little-endian vs. big-endian) and rearrange input channels to
+match the format requested by the plugin. The library will then call
+<a href="ao_plugin_play.html">ao_plugin_play()</a> for the block of
+audio data.
<li>When the client app closes the audio device, the library calls <a
href="ao_plugin_close.html">ao_plugin_close()</a> to close the device,
@@ -95,20 +97,22 @@
<li>Make a new directory in the src/plugins directory with the short name of your plugin.
-<li>Copy the contents of one of the other plugin directories into your
-directory. The Sun driver is a good example of a driver that uses
-system devices for output, and the ALSA driver is a good example of a
-plugin that uses an external library. Rename the source file to ao_shortname.c, where "shortname" is the short name of your plugin.
+<li>Study the contents of one of the other plugin directories. The
+Sun driver is a good example of a driver that uses system devices for
+output, and the ALSA driver is a good example of a plugin that uses an
+external library. Rename the source file to ao_shortname.c, where
+"shortname" is the short name of your plugin.
-<li>Edit the <a href="ao_info.html">ao_info</a> structure.
+<li>Create an <a href="ao_info.html">ao_info</a> structure.
<li>Implement the all of the methods defined in the <a
href="plugin-api.html">plugin API</a>.
-<li>Edit the files ("shortname" is as described above): configure.in,
-src/plugins/Makefile.am, src/plugins/shortname/Makefile.am. There
-should be a an configure option to disable your plugin. Look at the
-existing configure.in file for examples of how to do this.
+<li>Create src/plugins/shortname/Makefile.am ("shortname" is as
+described above) and edit the files configure.ac and
+src/plugins/Makefile.am. There should be a an configure option to
+disable your plugin. Look at the existing configure.ac file for
+examples of how to do this.
<li>Test it thoroughly! :)
@@ -144,6 +148,34 @@
your plugin needs. The libao core will reorder the bytes for you if
it necessary.
+<li>Depending on the driver, a channel mapping may be very easy,
+tricky, or impossible. If the audio backend uses a fixed numbering
+for its channels (not necessarily a fixed order), your new driver can
+simply set an <tt>output_matrix</tt> and
+<tt>output_matrix_ordering</tt> in <a
+href="ao_plugin_device_init.html">ao_plugin_device_init()</a> and not
+need to worry about much else. Libao will automatically permute
+channels, as well has hand over the needed mapping information in a
+form that can usually be submitted directly to the audio backend
+during device configuration. Examples of drivers that do this are WAV,
+ALSA and PULSE.
+
+<li>Some drivers can't perform channel mapping determination until
+they see the input sample format in <a
+href="ao_plugin_open.html">ao_plugin_open()</a>. Such a driver
+supports channel mapping by setting the overall
+<tt>output_matrix_ordering</tt> in <a
+href="ao_plugin_device_init.html">ao_plugin_device_init()</a> and then
+setting the <tt>inter_matrix</tt> field in <a
+href="ao_plugin_open.html">ao_plugin_open()</a>. One driver that
+works this way is the Roar plugin.
+
+<li>The number of channels to be sent to the hardware is not the
+number of channels declared in the sample format; use the
+device->output_channels field instead. The number of channels an
+application submits to libao is not necessarily the same as the number
+of channels libao sends to the plugin to play.
+
<li>Read the <a href="drivers.html">driver documentation</a> to see
what priority you should set for your plugin in the <a
href="ao_info.html">ao_info</a> structure.
@@ -159,7 +191,7 @@
<td align=right><p class=tiny><a href="http://www.xiph.org/">xiph.org</a><br><a href="mailto:monty at xiph.org">monty at xiph.org</a></p></td>
</tr><tr>
<td><p class=tiny>libao documentation</p></td>
-<td align=right><p class=tiny>libao version 0.9.0 - 20100124</p></td>
+<td align=right><p class=tiny>libao version 1.0.0 - 20100324</p></td>
</tr>
</table>
Modified: trunk/ao/src/plugins/macosx/ao_macosx.c
===================================================================
--- trunk/ao/src/plugins/macosx/ao_macosx.c 2010-03-24 06:05:54 UTC (rev 17010)
+++ trunk/ao/src/plugins/macosx/ao_macosx.c 2010-03-24 06:48:31 UTC (rev 17011)
@@ -56,7 +56,7 @@
{
AO_TYPE_LIVE,
"MacOS X AUHAL output",
- "macosx_auhal",
+ "macosx",
"Monty <monty at xiph.org>",
"",
AO_FMT_NATIVE,
More information about the commits
mailing list