diff DOCS/tech/general.txt @ 4582:9c13e907f284

applied patch from Andres Johansson

--- a/DOCS/tech/general.txt	Fri Feb 08 04:18:01 2002 +0000
+++ b/DOCS/tech/general.txt	Fri Feb 08 13:54:57 2002 +0000
@@ -273,11 +273,64 @@
   all the bytes, it has to give back how many have been used (copied to
   buffer).
 
-static int get_delay();
-  Has to return how many bytes are in the audio buffer. Be exact, if possible,
-  since the whole timing depends on this! In the worst case, return the size
-  of the buffer.
+static float get_delay(); 
+  Returns how long time it will take to play the data currently in the
+  output buffer. Be exact, if possible, since the whole timing depends
+  on this! In the worst case, return the maximum delay.
 
 !!! Because the video is synchronized to the audio (card), it's very important
-!!! that the get_space and get_delay functions be correctly implemented!
+!!! that the get_space and get_delay functions are correctly implemented!
 
+6.a audio plugins
+  Audio plugins are used for processing the audio data before it
+  reaches the soundcard driver. A plugin can change the following 
+  aspects of the audio data stream:
+  1. Sample format
+  2. Sample rate
+  3. Number of channels
+  4. The data itself (i.e. filtering and other sound effects)
+  5. The delay (almost all plugins does this)
+  The plugin interface is implemented as a pseudo device driver with
+  the catchy name "plugin". The plugins are executed sequentially
+  ordered by the "-aop list=plugin1,plugin2,..." command line switch.
+  To add plugins add an entry in audio_plugin.h the makefile and
+  create a source file named "pl_whatever.c". Input parameters are
+  added to audio_plugin.h and to cfg-mplayer.h. A good starting point
+  for writing plugins is pl_delay.c. Below is a description of what
+  the functions does:
+    
+static int control(int cmd, int arg);
+  This is for reading/setting plugin-specific and other special
+  parameters and can be used for keyboard input for example. All
+  plugins bust respond to cmd=AOCONTROL_PLUGIN_SET_LEN which is part
+  of the initialization of the plugin. When this command is received
+  the parameter pl_delay.len will contain the maximum size of data the
+  plugin can produce. This can be used for calculating and allocating
+  buffer space for the plugin. Before the function exits the parameter
+  pl_delay.len must be set to the maximum data size the plugin can
+  receive. Return CONTROL_OK for success and CONTROL_ERROR for fail,
+  other control codes are found in audio_out.h.
+
+static int init();
+  This function is for initializing the plugin, it is called once
+  before the playing is started. In this function the plugin can read
+  AND write to the ao_plugin_data struct to determine and set input
+  and output parameters. It is important to write to the
+  ao_plugin_data.sz_mult and ao_plugin_data.delay_fix parameters if
+  the plugin changes the data size or adds delay. Return 0 for fail
+  and 1 for success.
+
+static void uninit()
+  Called before mplayer exits. Used for deallocating dynamic buffers.
+
+static void reset()
+  Called during reset can be used to empty buffers. Mplayer calls this
+  function when pause is pressed.
+
+static int play() 
+  Called for every block of audio data sent through the plugin. This
+  function should be optimized for speed. The incoming data is found
+  in ao_plugin_data.data having length ao_plugin_data.len. These two
+  parameters should be changed by the plugin. Return 1 for success and
+  0 for fail.
+