Changes made to mad plugin:
[vlc.git] / plugins / mad / DESIGN
1 File:   Plugin mad for vlc is based upon libmad from the mad distribution.
2 Author: Jean-Paul Saman <jpsaman@wxs.nl>
3
4 Directories:
5 ============
6 vlc/plugins/mad         : mad audio decoder plugin for vlc
7
8 Interface functions
9 ===================
10 The following interface functions are implemented in the mad plugin.
11
12 decoder_Probe   : vlc probes for plugin capabilities
13 decoder_Run     : vlc starts a decoder plugin by calling this function
14 InitThread      : routine to do some initializations
15 EndThread       : cleanup function
16
17 The following functions are callback functions for the mad decoder library:
18
19 libmad_input    : called when input data is needed
20 libmad_output   : called whenever a frame has been decoded
21 libmad_header   : called upon decoding of only a frame header
22 libmad_messages : libmad messages
23 libmad_error    : called whenever an error occured during the decoding process
24
25 Design: (ASCII art)
26 =======
27 It represents the function call flow viewed from the vlc main program. The main program is in charge of allocating decoders,
28 initializing, starting and stopping them.
29
30       ---------------   
31       |  <library>  |
32       |   libmad    |
33       ---------------
34             ^
35             |
36       ---------------           
37       |   <plugin>  |
38       |     mad     |
39       _______________
40             ^
41             |
42    ________________________
43    |  <decoder interface> |
44    | vlc plugin interface |
45    ________________________
46
47
48 Interface view:
49 ===============
50                                     [mad decoder plugin]
51                                    ----------------------
52         vlc decoder interface -> | mad_adec     mad_libmad | -> libmad
53                                    -----------------------
54
55 Rationel:
56 ========
57 Keeping libmad as a separate library on the system, either dynamic or statically linked in, makes maintenance so much simpeler.
58 Merging with a new libmad version should be straight forward as long as the interface stays stable.
59 There is another benefit: Disk (actually flash ROM) resources and memory are very limited on a iPaq.
60 Other programs or utilities like madplay and BBplay can make use of the same libmad version we do. In this way
61 limiting the needed storage place on disk (flash ROM). Also this is only possible when the interface stays the same.
62
63