libao2 stuff move dto libao2.txt

added reference to codecs related .txt files


git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@6849 b3059339-0415-0410-9bf9-f77b7e298cf2

2 files changed, 104 insertions, 93 deletions

diff --git a/DOCS/tech/general.txt b/DOCS/tech/general.txt
index e9ab6ee48d..a7a8c4c44f 100644
--- a/DOCS/tech/general.txt
+++ b/DOCS/tech/general.txt
@@ -211,104 +211,18 @@ Now, go on:
    ve_*.c - video encoder (used by mencoder)
    vf_*.c - video filter  (see option -vop)
 
+   On this topic, see also:
+   dr-methods.txt - Direct rendering, MPI buffer management for video codecs
+   codecs.conf.txt - How to write/edit codec configuration file (codecs.conf)
+   codec-devel.txt - Mike's hints about codec development - a bit OUTDATED
+   hwac3.txt - about SP/DIF audio passthrough
+
 5. libvo: this displays the frame.
 
    for details on this, read libvo.txt
 
 6. libao2: this control audio playing
-
-  As in libvo (see 5.) also here are some drivers, based on the same API:
-
-static int control(int cmd, int arg);
-  This is for reading/setting driver-specific and other special parameters.
-  Not really used for now.
-
-static int init(int rate,int channels,int format,int flags);
-  The init of driver, opens device, sets sample rate, channels, sample format
-  parameters.
-  Sample format: usually AFMT_S16_LE or AFMT_U8, for more definitions see
-  dec_audio.c and linux/soundcards.h files!
-
-static void uninit();
-  Guess what.
-  Ok I help: closes the device, not (yet) called when exit.
-
-static void reset();
-  Resets device. To be exact, it's for deleting buffers' contents,
-  so after reset() the previously received stuff won't be output.
-  (called if pause or seek)
-
-static int get_space();
-  Returns how many bytes can be written into the audio buffer without
-  blocking (making caller process wait). If the buffer is (nearly) full,
-  has to return 0!
-  If it never gives 0, MPlayer won't work!
-
-static int play(void* data,int len,int flags);
-  Plays a bit of audio, which is received throught the "data" memory area, with
-  a size of "len". The "flags" isn't used yet. It has to copy the data, because
-  they can be overwritten after the call is made. Doesn't really have to use
-  all the bytes, it has to give back how many have been used (copied to
-  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 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.
+   for details on this, read libao2.txt
 
diff --git a/DOCS/tech/libao2.txt b/DOCS/tech/libao2.txt
new file mode 100644
index 0000000000..077d2c33af
--- /dev/null
+++ b/DOCS/tech/libao2.txt
@@ -0,0 +1,97 @@
+6. libao2: this control audio playing
+
+  As in libvo (see 5.) also here are some drivers, based on the same API:
+
+static int control(int cmd, int arg);
+  This is for reading/setting driver-specific and other special parameters.
+  Not really used for now.
+
+static int init(int rate,int channels,int format,int flags);
+  The init of driver, opens device, sets sample rate, channels, sample format
+  parameters.
+  Sample format: usually AFMT_S16_LE or AFMT_U8, for more definitions see
+  dec_audio.c and linux/soundcards.h files!
+
+static void uninit();
+  Guess what.
+  Ok I help: closes the device, not (yet) called when exit.
+
+static void reset();
+  Resets device. To be exact, it's for deleting buffers' contents,
+  so after reset() the previously received stuff won't be output.
+  (called if pause or seek)
+
+static int get_space();
+  Returns how many bytes can be written into the audio buffer without
+  blocking (making caller process wait). If the buffer is (nearly) full,
+  has to return 0!
+  If it never gives 0, MPlayer won't work!
+
+static int play(void* data,int len,int flags);
+  Plays a bit of audio, which is received throught the "data" memory area, with
+  a size of "len". The "flags" isn't used yet. It has to copy the data, because
+  they can be overwritten after the call is made. Doesn't really have to use
+  all the bytes, it has to give back how many have been used (copied to
+  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 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.
+