ao/doc/plugin-overview.html

   1 <html>
   2
   3 <head>
   4 <title>libao - Documentation</title>
   5 <link rel=stylesheet href="style.css" type="text/css">
   6 </head>
   7
   8 <body bgcolor=white text=black link="#5555ff" alink="#5555ff" vlink="#5555ff">
   9 <table border=0 width=100%>
  10 <tr>
  11 <td><p class=tiny>libao documentation</p></td>
  12 <td align=right><p class=tiny>libao version 0.8.5 - 20040312</p></td>
  13 </tr>
  14 </table>
  15
  16 <h1>libao Plugin Writer's Overview</h1>
  17
  18 <p>
  19 Plugins are drivers that are loaded dynamically when libao is first
  20 initialized by the client application.  Drivers that are operating
  21 system dependent, like the <tt>oss</tt> and <tt>sun</tt> drivers, or
  22 that depend on external libraries, like the <tt>esd</tt> driver, must
  23 be implemented as plugins in order to keep binary packagers happy.
  24 There are also statically linked drivers, which are written in a
  25 nearly identical way, but won't be covered here.  In nearly all cases,
  26 a dynamically loadable plugin is the preferred way to write a driver,
  27 and the required way if the driver depends upon any external
  28 libraries.
  29 </p>
  30
  31 <h2>Life Cycle</h2>
  32
  33 <p>
  34 The life cycle of a plugin is:
  35 <ul>
  36 <li>When libao is first <a href="ao_initialize.html">initialized</a>,
  37 it loads all of the plugins from disk.
  38
  39 <li>Libao then <a href="ao_plugin_test.html">tests</a> each plugin to
  40 see if can be used as the default driver.
  41
  42 <li>When the user opens a device, libao will:
  43
  44   <ul>
  45
  46   <li>Call <a
  47   href="ao_plugin_device_init.html">ao_plugin_device_init()</a> to
  48   allow the plugin to allocate and initialize any private data
  49   structures it will use.
  50
  51   <li>Call <a
  52   href="ao_plugin_set_option.html">ao_plugin_set_option()</a> for each
  53   parameter passed to the library by the client application.
  54
  55   <li>Call <a href="ao_plugin_open.html">ao_plugin_open.html</a> to
  56   open the device for playback.
  57
  58   </ul>
  59
  60 <li>Each time the client app calls <a
  61 href="ao_play.html">ao_play()</a>, the library will reorder the byte
  62 format (little-endian vs. big-endian) to match the format requested by
  63 the plugin.  The library will then call <a href="ao_plugin_play.html">ao_plugin_play()</a> for the block of audio data.
  64
  65 <li>When the client app closes the audio device, the library calls <a
  66 href="ao_plugin_close.html">ao_plugin_close()</a> to close the device,
  67 followed by a call to <a
  68 href="ao_plugin_clear.html">ao_plugin_device_clear()</a> to deallocate
  69 the private data structures.
  70
  71 <li>When the library is <a href="ao_shutdown.html">shutdown</a>, the
  72 plugin will be unloaded from memory.
  73
  74 </ul>
  75
  76 In case of errors, <a
  77 href="ao_plugin_device_clear.html">ao_plugin_device_clear()</a> will
  78 always be called if <a
  79 href="ao_plugin_device_init.html">ao_plugin_device_init()</a> executed
  80 successfully.  Similarly, <a
  81 href="ao_plugin_close.html">ao_plugin_close()</a> will always be
  82 called if <a href="ao_plugin_open.html">ao_plugin_open()</a> executed
  83 successfully.
  84 </p>
  85
  86 <h2>Creating a New Plugin</h2>
  87
  88 <p>
  89 In order to write a new plugin, follow these steps:
  90 <ul>
  91
  92 <li>Decide upon a new short name for your plugin.  It should be less
  93 than 8 characters and contain only alphanumeric characters
  94 (underscores are okay, but discouraged).
  95
  96 <li>Make a new directory in the src/plugins directory with the short name of your plugin.
  97
  98 <li>Copy the contents of one of the other plugin directories into your
  99 directory.  The Sun driver is a good example of a driver that uses
 100 system devices for output, and the ALSA driver is a good example of a
 101 plugin that uses an external library.  Rename the source file to ao_shortname.c, where "shortname" is the short name of your plugin.
 102
 103 <li>Edit the <a href="ao_info.html">ao_info</a> structure.
 104
 105 <li>Implement the all of the methods defined in the <a
 106 href="plugin-api.html">plugin API</a>.
 107
 108 <li>Edit the files ("shortname" is as described above): configure.in,
 109 src/plugins/Makefile.am, src/plugins/shortname/Makefile.am.  There
 110 should be a an configure option to disable your plugin.  Look at the
 111 existing configure.in file for examples of how to do this.
 112
 113 <li>Test it thoroughly!  :)
 114
 115 <li>Send a tarball of the src/plugin/shortname directory (only this
 116 directory, please!) and a cvs diff -u of the changes you have made to
 117 the <a href="mailto:vorbis-dev@xiph.org">vorbis-dev</a> list and we'll
 118 take a look at it for inclusion.
 119
 120 </ul>
 121 </p>
 122
 123 <h2>API Implementation Tips</h2>
 124
 125 <p>
 126 <ul>
 127
 128 <li>Remember to close any devices/connections you openned in <a
 129 href="ao_plugin_test.html">ao_plugin_test()</a>.  <li>Although you
 130 should try to allocate all of your data structures in <a
 131 href="ao_plugin_device_init.html">ao_plugin_device_init()</a>, there
 132 are cases where you won't be able to allocate memory until <a
 133 href="ao_plugin_open.html">ao_plugin_open()</a> is called.  That is
 134 acceptable, but the rule is that you must deallocate memory in <a
 135 href="ao_plugin_close.html">ao_plugin_close()</a> that was allocated
 136 in <a href="ao_plugin_open.html">ao_plugin_open()</a> and deallocate
 137 memory in <a
 138 href="ao_plugin_device_clear.html">ao_plugin_device_clear()</a> that
 139 was allocated in <a
 140 href="ao_plugin_device_init.html">ao_plugin_device_init()</a>.
 141
 142 <li>Don't forget to set device->driver_byte_format in <a
 143 href="ao_plugin_open.html">ao_plugin_open()</a> to the byte ordering
 144 your plugin needs.  The libao core will reorder the bytes for you if
 145 it necessary.
 146
 147 <li>Read the <a href="drivers.html">driver documentation</a> to see
 148 what priority you should set for your plugin in the <a
 149 href="ao_info.html">ao_info</a> structure.
 150
 151 </ul>
 152 </p>
 153
 154 <br><br>
 155 <hr noshade>
 156 <table border=0 width=100%>
 157 <tr valign=top>
 158 <td><p class=tiny>copyright &copy; 2001-2003 Stan Seibert</p></td>
 159 <td align=right><p class=tiny><a href="http://www.xiph.org/">xiph.org</a><br><a href="mailto:volsung@xiph.org">volsung@xiph.org</a></p></td>
 160 </tr><tr>
 161 <td><p class=tiny>libao documentation</p></td>
 162 <td align=right><p class=tiny>libao version 0.8.5 - 20040312</p></td>
 163 </tr>
 164 </table>
 165
 166 </body>
 167
 168 </html>