From cdb9bc51390dab9b2b95916c7d3ec3497c7a4050 Mon Sep 17 00:00:00 2001
From: Takashi Iwai <tiwai@suse.de>
Date: Thu, 23 Oct 2003 14:42:47 +0000
Subject: [PATCH] added more documents and examples about plugins.

---
 src/pcm/pcm_dmix.c   | 68 ++++++++++++++++++++++++++++++++++++++++++++
 src/pcm/pcm_dshare.c |  5 ++++
 src/pcm/pcm_dsnoop.c |  4 +++
 src/pcm/pcm_hooks.c  | 15 ++++++++++
 src/pcm/pcm_multi.c  | 37 ++++++++++++++++++++++++
 src/pcm/pcm_share.c  |  4 +++
 6 files changed, 133 insertions(+)

diff --git a/src/pcm/pcm_dmix.c b/src/pcm/pcm_dmix.c
index cda70440..b6d76c8d 100644
--- 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 bcb051f7..f49a6a2a 100644
--- 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 28baa4d2..6571f602 100644
--- 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 620a2dca..ea3e117c 100644
--- 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 6a4babf8..2a530bf5 100644
--- 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 50bd3a64..8b978400 100644
--- 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
-- 
2.47.1