added more documents and examples about plugins.

diff --git a/src/pcm/pcm_dmix.c b/src/pcm/pcm_dmix.c
index cda70440195a8310e3c6fc4037bbf346e97d26c7..b6d76c8dce30f885ef8c1cb56344b81019c7d735 100644 (file)
--- a/src/pcm/pcm_dmix.c
+++ b/src/pcm/pcm_dmix.c
@@ -958,6 +958,74 @@ pcm.name {
 }
 \endcode
 
+<code>ipc_key</code> specfies the unique IPC key in integer.
+This number must be unique for each different dmix definition,
+since the shared memory is created with this key number.
+When <code>ipc_key_add_uid</code> is set true, the uid value is
+added to the value set in <code>ipc_key</code>.  This will
+avoid the confliction of the same IPC key with different users
+concurrently.
+
+Note that the dmix plugin itself supports only a single configuration.
+That is, it supports only the fixed rate (default 48000), format
+(\c S16), channels (2), and period_time (125000).
+For using other configuration, you have to set the value explicitly
+in the slave PCM definition.  The rate, format and channels can be
+covered by an additional \ref pcm_plugins_dmix "plug plugin",
+but there is only one base configuration, anyway.
+
+An example configuration for setting 44100 Hz, \c S32_LE format
+as the slave PCM of "hw:0" is like below:
+\code
+pcm.dmix_44 {
+       type dmix
+       ipc_key 321456  # any unique value
+       ipc_key_add_uid true
+       slave {
+               pcm "hw:0"
+               format S32_LE
+               rate 44100
+       }
+}
+\endcode
+You can hear 48000 Hz samples still using this dmix pcm via plug plugin
+like:
+\code
+% aplay -Dplug:dmix_44 foo_48k.wav
+\endcode
+
+For using the dmix plugin for OSS emulation device, you have to set
+the period and the buffer sizes in power of two.  For example,
+\code
+pcm.dmixoss {
+       type dmix
+       ipc_key 321456  # any unique value
+       ipc_key_add_uid true
+       slave {
+               pcm "hw:0"
+               period_time 0
+               period_size 1024  # must be power of 2
+               buffer_size 8192  # ditto
+       }
+}
+\endcode
+<code>period_time 0</code> must be set, too, for resetting the
+default value.  In the case of soundcards with multi-channel IO,
+adding the bindings would help
+\code
+pcm.dmixoss {
+       ...
+       bindings {
+               0 0   # map from 0 to 0
+               1 1   # map from 1 to 1
+       }
+}
+\endcode
+so that only the first two channels are used by dmix.
+Also, note that ICE1712 have the limited buffer size, 5513 frames
+(corresponding to 640 kB).  In this case, reduce the buffer_size
+to 4096.
+
 \subsection pcm_plugins_dmix_funcref Function reference
 
 <UL>

diff --git a/src/pcm/pcm_dshare.c b/src/pcm/pcm_dshare.c
index bcb051f717a69e1368ba6064dc6aea340916a9b2..f49a6a2ae5bffb321aed0d87d5d66d5cb2d49315 100644 (file)
--- a/src/pcm/pcm_dshare.c
+++ b/src/pcm/pcm_dshare.c
@@ -681,6 +681,11 @@ int snd_pcm_dshare_open(snd_pcm_t **pcmp, const char *name,
 \section pcm_plugins_dshare Plugin: dshare
 
 This plugin provides sharing channels.
+Unlike \ref pcm_plugins_share "share plugin", this plugin doesn't need
+the explicit server program but accesses the shared buffer concurrently
+from each client as well as \ref pcm_plugins_dmix "dmix" and
+\ref pcm_plugins_dsnoop "dsnoop" plugins do.
+The parameters below are almost identical with these plugins.
 
 \code
 pcm.name {

diff --git a/src/pcm/pcm_dsnoop.c b/src/pcm/pcm_dsnoop.c
index 28baa4d2f37bd0f349153766ee72a25cef3ce6e3..6571f6021abcb8d7a4987d8977dfe9c97d7b3d07 100644 (file)
--- a/src/pcm/pcm_dsnoop.c
+++ b/src/pcm/pcm_dsnoop.c
@@ -632,6 +632,10 @@ int snd_pcm_dsnoop_open(snd_pcm_t **pcmp, const char *name,
 \section pcm_plugins_snoop Plugin: dsnoop
 
 This plugin splits one capture stream to more.
+It works the reverse way of \ref pcm_plugins_dmix "dmix plugin",
+reading the shared capture buffer from many clients concurrently.
+The meaning of parameters below are almost identical with
+dmix plugin.
 
 \code
 pcm.name {

diff --git a/src/pcm/pcm_hooks.c b/src/pcm/pcm_hooks.c
index 620a2dcaea01982773d079d00adc051b61238b4e..ea3e117ca8ab1a1feccb7b78f2a8f00983824864 100644 (file)
--- a/src/pcm/pcm_hooks.c
+++ b/src/pcm/pcm_hooks.c
@@ -370,6 +370,11 @@ int snd_pcm_hooks_open(snd_pcm_t **pcmp, const char *name, snd_pcm_t *slave, int
 
 \section pcm_plugins_hooks Plugin: hooks
 
+This plugin is used to call some 'hook' function when this plugin is opened,
+modified or closed.
+Typically, it is used to change control values for a certain state
+specially for the PCM (see the example below).
+
 \code
 # Hook arguments definition
 hook_args.NAME {
@@ -418,6 +423,7 @@ Example:
                                name "Wave Surround Playback Volume"
                                preserve true
                                lock true
+                               optional true
                                value [ 0 0 ]
                        }
                        {
@@ -429,6 +435,15 @@ Example:
                ]
        }
 \endcode
+Here, the controls "Wave Surround Playback Volume" and "EMU10K1 PCM Send Volume"
+are set to the given values when this pcm is accessed.  Since these controls
+take multi-dimensional values, the <code>value</code> field is written as
+an array.
+When <code>preserve</code> is true, the old values are saved and restored
+when the pcm is closed.  The <code>lock</code> means that the control is
+locked during this pcm is opened, and cannot be changed by others.
+When <code>optional</code> is set, no error is returned but ignored
+even if the specified control doesn't exist.
 
 \subsection pcm_plugins_hooks_funcref Function reference
 

diff --git a/src/pcm/pcm_multi.c b/src/pcm/pcm_multi.c
index 6a4babf8fd7109b3457a11b7af77982516064a4b..2a530bf5974ddedf28b9109e0fe321bf5e98604f 100644 (file)
--- a/src/pcm/pcm_multi.c
+++ b/src/pcm/pcm_multi.c
@@ -765,6 +765,43 @@ pcm.name {
 }
 \endcode
 
+For example, to bind two PCM streams with two-channel stereo (hw:0,0 and
+hw:0,1) as one 4-channel stereo PCM stream, define like this:
+\code
+pcm.quad {
+       type multi
+
+       slaves.a.pcm "hw:0,0"
+       slaves.a.channels 2
+       slaves.b.pcm "hw:0,1"
+       slaves.b.channels 2
+
+       bindings.0.slave a
+       bindings.0.channel 0
+       bindings.1.slave a
+       bindings.1.channel 1
+       bindings.2.slave b
+       bindings.2.channel 0
+       bindings.3.slave b
+       bindings.3.channel 1
+}
+\endcode
+Note that the resultant pcm "quad" is not in the interleaved format
+but in the "complex" format.  Hence, it's not accessible by applications
+which can handle only the interleaved (or the non-interleaved) format.
+In such a case, wrap this PCM with \ref pcm_plugins_route "route" or
+\ref pcm_plugins_plug "plug" plugin.
+\code
+pcm.quad2 {
+       type route
+       slave.pcm "quad"
+       ttable.0.0 1
+       ttable.1.1 1
+       ttable.2.2 1
+       ttable.3.3 1
+}
+\endcode
+
 \subsection pcm_plugins_multi_funcref Function reference
 
 <UL>

diff --git a/src/pcm/pcm_share.c b/src/pcm/pcm_share.c
index 50bd3a641d68f28c2b195fb449f788d9dd237dfd..8b9784001021508fd4edd9ffce0ec23466e1b4c0 100644 (file)
--- a/src/pcm/pcm_share.c
+++ b/src/pcm/pcm_share.c
@@ -1503,6 +1503,10 @@ the channel zero is used with first client, the channel cannot be used with
 second one. If you are looking for a mixing plugin, use the
 \ref pcm_plugins_dmix "dmix plugin".
 
+The difference from \ref pcm_plugins_dshare "dshare plugin" is that
+share plugin requires the server program "aserver", while dshare plugin
+doesn't need the explicit server but access to the shared buffer.
+
 \code
 pcm.name {
         type share              # Share PCM