2 \input texinfo @c -*-texinfo-*-
4 @setfilename ahiusr.info
5 @settitle @sc{Ahi} User's Guide
14 @c Set ahiver and docver to current release version
18 @c Part 2: Summary Description and Copyright
19 @c ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
22 This file documents AHI release @value{ahiver}, a hardware independent
23 audio subsystem for Amiga. The version number of this document is
26 Copyright @copyright{} 1994-2005 Martin Blom.
28 Permission is granted to make and distribute verbatim copies of this manual
29 provided the copyright notice and this permission notice are preserved on
33 Permission is granted to process this file through TeX and print the
34 results, provided the printed document carries a copying permission notice
35 identical to this one except for the removal of this paragraph (this
36 paragraph not being relevant to the printed manual).
39 Permission is granted to copy and distribute modified versions of this
40 manual under the conditions for verbatim copying, provided also that the
41 sections entitled ``Distribution'', ``GPL'' and ``LGPL'' are included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this manual
47 into another language, under the above conditions for modified versions,
48 except that this permission notice may be stated in a translation approved
49 by the Free Software Foundation.
51 @sc{This publication is provided by the author ``as is'' and any express or
52 implied warranties, including, but not limited to, the implied warranties
53 of merchantability and fitness for a particular purpose are disclaimed. In
54 no event shall the author be liable for any direct, indirect, incidental,
55 special, exemplary, or consequential damages (including, but not limited
56 to, procurement of substitute goods or services; loss of use, data, or
57 profits; or business interruption) however caused and on any theory of
58 liability, whether in contract, strict liability, or tort (including
59 negligence or otherwise) arising in any way out of the use of this
60 publication, even if advised of the possibility of such damage.}
65 $Log: ahiusr.texinfo,v $
66 Revision 5.9.2.8 2005/09/22 20:09:18 martin
67 Docs/ahiusr.texinfo: Added Gunther Nikl and Davy Wentzler to
68 "Contributors". Removed all contributor e-mail addresses.
70 Revision 5.9.2.7 2005/06/19 21:43:57 martin
71 AHItoccataPlayBufferSize and AHItoccataRecordBufferSize.
73 Revision 5.9.2.6 2005/02/02 21:49:52 martin
74 * Updated all copyright years to 2005.
76 * Bumped all version numbers to 6.0.
78 * Docs/ahidev.texinfo (The Author): Updated the authors address (5
81 Revision 5.9.2.5 2005/01/08 22:38:09 martin
82 Added note about the volume scaling.
83 Removed list of names in Honourable mention.
85 Revision 5.9.2.4 2004/11/02 13:18:53 martin
86 Updated copyright year and removed almost all CVS/RCS tags from the
89 Revision 5.9.2.3 2004/10/23 12:19:39 martin
92 Revision 5.9.2.2 2004/09/08 13:56:37 martin
93 Added description of the default anti-click time
95 Revision 5.9.2.1 2004/06/08 21:16:16 martin
96 Added 7.1 multichannel support.
98 Revision 5.9 2004/06/01 19:00:01 martin
101 Revision 5.8 2004/02/19 20:45:03 martin
102 Added note about AddAudioModes and sound card/AC97 initializing.
104 Revision 5.7 2003/07/20 17:04:14 martin
105 Replaced Nicolas Sallin with Genesi and bbrv.
107 Revision 5.6 2003/02/09 15:04:48 martin
108 Added a link to CyberSound.lha for 14 bit Paula calibration.
109 Clarified the relationshit between units and sound cards.
111 Revision 5.5 2003/02/08 14:14:18 martin
112 Wrote about the "Paula:DMA 8 bit stereo" mode.
114 Revision 5.4 2003/01/23 23:23:23 martin
115 Updated the list of supported sound cards.
117 Revision 5.3 2003/01/23 23:15:45 martin
118 Updated the Acknowledgments chapter. Added Donors and Honourable
119 mention sections. Updated my address.
121 Revision 5.2 2003/01/19 16:16:39 martin
122 Added not about dynamic volume adjusting in V6.
124 Revision 5.1 2003/01/19 12:22:41 martin
125 Another year, another copyright update.
126 ... which seems to have caused the translation files to change slightly.
128 Revision 5.0 2000/11/28 00:16:20 lcs
129 Bumped CVS revision to 5.0.
131 Revision 4.23 1999/09/20 21:08:52 lcs
132 Minor rearrengment of the Acknowledgements chapter.
133 Added Frank Wille to Contributors.
135 Revision 4.22 1999/09/19 14:05:28 lcs
136 Changed the license text.
139 Revision 4.21 1999/03/28 22:32:49 lcs
140 AHI is now GPL/LGPL software.
141 Make target bindist work correctly when using a separate build directory.
142 Small first steps towards a WarpOS PPC version.
144 Revision 4.20 1999/01/10 19:27:48 lcs
145 The move to GNU make is done.
147 Revision 4.19 1999/01/10 16:07:58 lcs
148 Moved to GNU make (still moving...)
150 Revision 4.18 1998/12/06 11:51:25 lcs
151 Removed the stuff about paula not being exactly like the filesave driver
154 Revision 4.17 1998/10/25 15:38:30 lcs
155 Added note about that paula.audio cannot behave exactly like filesave.audio.
157 Revision 4.16 1998/10/25 13:31:50 lcs
158 Added info about the paula.audio AHIpaulaFakeMixFreq variable.
160 Revision 4.15 1998/03/11 09:28:51 lcs
161 Added info about how to make the Amiga video 31 kHz.
163 Revision 4.14 1998/01/18 19:50:42 lcs
164 Updated the acknowledges. Probably more.
166 Revision 4.13 1997/12/17 19:53:17 lcs
167 Added the translators of of Hrvatski and Magyar to the hall of fame...
169 Revision 4.12 1997/11/02 02:01:48 lcs
170 Added Concierto (again!).
172 Revision 4.11 1997/10/21 01:33:40 lcs
173 The version number is now the AHI release version, not the documents version.
175 Revision 4.10 1997/09/30 13:11:09 lcs
176 Added reasons why "Fast" or "Hifi" modes should be used.
178 Revision 4.9 1997/09/28 04:31:56 lcs
179 Added notes about Maestor Pro and Melody MPEG. Added Thorsten Hansen
180 to the contributors section. And some other minor things.
182 Revision 4.8 1997/09/18 00:51:00 lcs
183 Added Maestro Pro stuff.
185 Revision 4.7 1997/08/10 15:38:57 lcs
186 Minor changes. added @@ahi macro!
188 Revision 4.6 1997/08/03 22:48:26 lcs
189 Added Concierto to list of supported sound cards.
190 Added Christian Buchner to the Acknowledgments section.
191 Changed Teemu Suikki's email address.
193 Revision 4.5 1997/07/27 19:04:10 lcs
194 Added description of the AHIpaulaSwapChannels env. variable.
196 Revision 4.4 1997/07/15 00:50:40 lcs
197 This is the second bugfix release of AHI 4.
199 Revision 4.3 1997/05/04 15:52:58 lcs
206 @c Part 3: Titlepage and Copyright
207 @c ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
211 @subtitle Hardware independent audio for Amiga
212 @subtitle AHI User's Guide for AHI release @value{ahiver}
213 @subtitle Document version @value{docver}
214 @author Martin 'Leviticus' Blom
218 @vskip 0pt plus 1filll
220 Copyright @copyright{} 1994-2005 Martin Blom.
222 Permission is granted to make and distribute verbatim copies of this manual
223 provided the copyright notice and this permission notice are preserved on
226 Permission is granted to copy and distribute modified versions of this
227 manual under the conditions for verbatim copying, provided also that the
228 sections entitled ``Distribution'', ``GPL'' and ``LGPL'' are included
229 exactly as in the original, and provided that the entire resulting
230 derived work is distributed under the terms of a permission notice
231 identical to this one.
233 Permission is granted to copy and distribute translations of this manual
234 into another language, under the above conditions for modified versions,
235 except that this permission notice may be stated in a translation approved
236 by the Free Software Foundation.
238 @sc{This publication is provided by the author ``as is'' and any express or
239 implied warranties, including, but not limited to, the implied warranties
240 of merchantability and fitness for a particular purpose are disclaimed. In
241 no event shall the author be liable for any direct, indirect, incidental,
242 special, exemplary, or consequential damages (including, but not limited
243 to, procurement of substitute goods or services; loss of use, data, or
244 profits; or business interruption) however caused and on any theory of
245 liability, whether in contract, strict liability, or tort (including
246 negligence or otherwise) arising in any way out of the use of this
247 publication, even if advised of the possibility of such damage.}
252 @c Part 4: `Top' Node and Master Menu
253 @c ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
255 @node Top, Overview, (dir), (dir)
259 @majorheading @sc{Ahi} User's Guide
261 For @sc{Ahi} release @value{ahiver}. Document version @value{docver}.
263 Copyright @copyright{} 1994-2005 Martin Blom
265 The latest release of @sc{Ahi} can always be found at
266 @url{http://www.lysator.liu.se/~lcs/ahi.html}.
269 * Overview:: Brief introduction
270 * Distribution:: What you are allowed to do and not
272 * System description:: The components of @sc{Ahi}
274 * The Author:: Who designed it?
275 * Acknowledgments:: Thanks, guys!
277 * GPL:: The main license
278 * LGPL:: The @code{ahi.device} license
280 * Concept Index:: Concept Index
286 @c Part 5: The Body of the Document
287 @c ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
290 @c ***********************************************************************
291 @c **** Overview *********************************************************
292 @c ***********************************************************************
294 @node Overview, Distribution, Top, Top
295 @comment node-name, next, previous, up
299 @cindex AHI, overview
300 @cindex Paula, custom chip
302 The @dfn{Amiga} has always had excellent sound capabilities. In 1986, they
303 were awesome. Today, well@enddots{} Perhaps not awesome, but still very
304 good. The OS interface, @code{audio.device} has however never been as good
305 as it could have been. It is tied hard to the underlying hardware, and
306 doesn't work very well for music. This has led to a situation where most
307 audio programs only use @code{audio.device} to allocate the audio resource,
308 and then poke around in the hardware registers---making it next to
309 impossible to replace the @dfn{Paula} chip @footnote{Paula is one of the
310 custom chips, and she is responsible for the sound (and more).
311 Unfortunately, this chip has not been updated since the very first Amiga
314 There have been attempts to write an @code{audio.device} clone that uses a
315 sound card instead of Paula, but so far nobody has succeeded. It is
316 definitely possible, but the question is if it is worth the trouble---too
317 many of the programs bang the hardware.
319 Entering @sc{Ahi} @footnote{The name @sc{Ahi} was chosen because the
320 functions in the system had to have a prefix, and the author couldn't come
321 up with anything better than @dfn{Audio Hardware Interface}, something that
322 he has regretted ever since. The suggested pronunciation is ``atchii'', as
323 in ``God bless!''.}. @sc{Ahi} is a new audio subsystem, designed to be
324 flexible, hardware independent, expandable and future safe. It is designed
325 with real-time applications in mind. It is designed to play @dfn{modules}
326 @footnote{Originally designed in 1986 by Karsten Obarski, modules have
327 become a de facto standard for game and demo music. The original format
328 has been improved many times, and many new music formats have---more or
329 less---been derived from it, including the popular @dfn{S3M} and @dfn{XM}
330 formats.} and sound effects as efficient as possible, taking advantage of
331 modern DSP-based sound cards.
333 Yet @sc{Ahi} allows applications that don't need full control over the
334 audio hardware to share the resource, so that many different programs can
335 play and record sound at the same time, without conflicts.
337 As a user you will hopefully not see much of @sc{Ahi}, other than the audio
338 mode requesters. They works almost exactly like screen mode requesters.
340 @sc{Ahi} was never supposed to be @emph{the} standard for hardware
341 independent audio. It was meant as a temporary solution until @dfn{Amiga
342 Technologies} delivered an official standard. However, the situation looks
343 worse and worse for every day that passes by, and this may be all you will
347 @c ***********************************************************************
348 @c **** Distribution *****************************************************
349 @c ***********************************************************************
351 @node Distribution, System description, Overview, Top
352 @comment node-name, next, previous, up
353 @chapter Distribution
358 @cindex Legal nonsense
359 @cindex Software license
362 Copyright @copyright{} 1994-2005 Martin Blom
364 @sc{Ahi} is available under a dual license. The device itself is under
365 the ``GNU Library General Public License'' (@pxref{LGPL}), while the
366 utility programs and the @code{AUDIO:} device is covered by the ``GNU
367 General Public License'' (@pxref{GPL}).
369 If you use this software in a commercial or shareware product, please
370 consider giving the author (@pxref{The Author})---and preferably each one
371 of the contributors too (see @cite{@sc{Ahi} User's Guide})---an original or
372 registered copy or sample of your work. Should you want to distribute the
373 @sc{Ahi} software with your own product, there is really nothing to
376 @c ***********************************************************************
377 @c **** System description ***********************************************
378 @c ***********************************************************************
380 @node System description, The Author, Distribution, Top
381 @comment node-name, next, previous, up
382 @chapter System description
384 @cindex System description
387 * AddAudioModes:: Database maintenance and more
388 * AHI:: Preferences program
389 * AHI-Handler:: DOS-device
391 * System Files:: The files in @file{DEVS:}
395 @c ***********************************************************************
396 @c **** AddAudioModes ****************************************************
397 @c ***********************************************************************
399 @node AddAudioModes, AHI, System description, System description
400 @comment node-name, next, previous, up
401 @section AddAudioModes
403 @cindex AddAudioModes
408 [FILES <file|pattern>] [QUIET] [REFRESH] [REMOVE] [DBLSCAN]
411 FILES/M,QUIET/S,REFRESH/S,REMOVE/S,DBLSCAN/S
414 To build and remove a list of audio modes that @sc{Ahi} can understand.
420 @code{AddAudioModes} is used to build and remove a list of audio modes that
421 @sc{Ahi} can understand. The definitions of the audio modes are stored in
422 @file{DEVS:Audiomodes} (@pxref{The Mode Descriptors}). Normally you don't
423 have to run this program, since @code{ahi.device} automatically reads all
424 mode descriptors when it is used for the first time. It can, however, be
425 useful in installation scripts.
427 In addition to rebuilding the audio mode database, it has the side
428 effect that the audio drivers are loaded into memory. This causes the
429 audio hardware to be initialized and, perhaps, AC97 mixers to be set
430 up to the default, which is good if, for example, your CD is connected
433 The @samp{FILES} option specifies with descriptor(s) to be added to the
436 The @samp{QUIET} option, if specified, will suppress error and output
439 The @samp{REFRESH} option, if specified, will scan @file{DEVS:Audiomodes}
440 and add all descriptors found there to the current mode list.
442 The @samp{REMOVE} option, if specified, will flush the current audio mode
445 The @samp{DBLSCAN} option does not have anything to do with the audio mode
446 list. If specified, it will open and then immediately close a native,
447 double-scan screen. On some systems using a graphic card, this will enable
448 >28 kHz sample frequencies with the native audio. You need an appropriate
449 monitor driver in @file{DEVS:Monitors} to make it work.
453 @c ***********************************************************************
454 @c **** AHI **************************************************************
455 @c ***********************************************************************
457 @node AHI, AHI-Handler, AddAudioModes, System description
458 @comment node-name, next, previous, up
461 @cindex AHI, preferences program
468 [FROM <filename>] [EDIT] [USE] [SAVE] [PUBSCREEN <public screen name>
471 FROM,EDIT/S,USE/S,SAVE/S,PUBSCREEN/K
474 To specify default audio options
480 @code{AHI} without any arguments or with the @samp{EDIT} argument opens the
481 @sc{Ahi} preferences editor. The @samp{FROM} argument lets you specify a
482 file to open. This must be a file that was previously saved with the
483 @samp{Save As@dots{}} menu item of the @sc{Ahi} preferences editor. For
484 example, if you have saved a special configuration of the @sc{Ahi}
485 preferences editor to a file in the @file{Presets} drawer, you can use the
486 @samp{FROM} argument to open that file. If the @samp{USE} switch is also
487 given, the editor will not be opened, but the settings in the @samp{FROM}
488 file will be used. If the @samp{SAVE} switch is given, the editor will not
489 open, but the settings in the @samp{FROM} file will be saved. The
490 @samp{PUBSCREEN} option allows you to specify a public screen on which the
491 program will open its window.
496 AHI Prefs/Presets/AHI.Delfina USE
499 loads and uses the specifications saved in the @file{AHI.Delfina} file. If
500 the system is rebooted, the last saved specifications will be loaded.
504 Note that the preferences program requires either @code{bgui.library}
505 version 41 @footnote{@dfn{BGUI} is Copyright © 1996-1997 Ian J. Einman} or
506 @dfn{MUI} version 3.8 @footnote{@dfn{MUI} is Copyright © 1992-1997 Stefan
514 @node Menus, Pages, AHI, AHI
515 @comment node-name, next, previous, up
525 @node Project Menu, Edit Menu, Menus, Menus
526 @comment node-name, next, previous, up
527 @subsubsection @samp{Project} Menu
529 The @samp{Project} menu options let you save the editor settings to a
530 specific file and open previously saved files.
535 Loads the information from a specified preset file.
538 Specify the preset file in which to save the currently displayed settings.
539 The requester provides a default file name in the @file{Presets} drawer.
540 If you want to change it, type in the full path to a different file and
547 Exits the editor without performing any changes (the same as the
548 @samp{Cancel} gadget).
552 @node Edit Menu, Settings Menu, Project Menu, Menus
553 @comment node-name, next, previous, up
554 @subsubsection @samp{Edit} Menu
556 The @samp{Edit} menu options allow you to restore previously used settings
557 or the default settings. The options are:
561 @item Reset to Default
562 Returns the editor settings to the default settings.
565 Returns the editor settings to the last settings you saved.
568 Returns the editor to the settings displayed when the editor first opened.
573 @node Settings Menu, Help Menu, Edit Menu, Menus
574 @comment node-name, next, previous, up
575 @subsubsection @samp{Settings} Menu
577 The @samp{Settings} menu contains the @samp{Create Icons?} item that allows
578 you to save project icons representing your editor settings in the same
579 drawer as your files. For example, if you save the specifications to the
580 @file{SYS:Prefs/Presets/AHI.pre} file, the icon for the file appears in the
581 @samp{Presets} window. Double-click on the icon to activate the file's
584 @node Help Menu, , Settings Menu, Menus
585 @comment node-name, next, previous, up
586 @subsubsection @samp{Help} Menu
588 The @samp{Help} menu's items let you view the on-line ``@sc{Ahi} User's
589 Guide'' using AmigaGuide.
594 Brings up the chapter about the preferences program (this chapter).
596 @item AHI User's Guide@dots{}
597 Brings up the first page of ``@sc{Ahi} User's Guide''.
599 @item Concept Index@dots{}
600 Brings up the index of ``@sc{Ahi} User's Guide''.
605 @node Pages, , Menus, AHI
606 @comment node-name, next, previous, up
609 The preferences program's GUI is divided in two pages:
613 * Advanced settings::
616 @node Mode settings, Advanced settings, Pages, Pages
617 @comment node-name, next, previous, up
618 @subsubsection @samp{Mode settings} Page
620 @cindex Mode settings
621 @cindex Audio mode settings
622 @cindex Settings, audio mode
623 @cindex Preferences, audio mode
625 On this page you select which audio mode to use. You can select audio
626 mode for both low-level programs (@samp{Music unit}) and other
627 programs (@samp{Unit n}) that don't require low-level audio access
628 such as the @code{AUDIO:} device (@pxref{AHI-Handler}), sample players
629 etc. You can also select the sample mixing (and recording) frequency
630 to use and how many channels you wish use @footnote{The more channels
631 you select, the more sounds can you play at the same time. However,
632 due to the nature of sound mixing in version 4, the volume will
633 decrease as well. This limitation is not present in version 6, where
634 the volume will be adjusted dynamically. If you try to play more
635 sounds at the same time than there are channels, the least important
636 sounds will be muted until the other sounds have finished playing.}.
637 Furthermore, you can set three hardware properties of your sound
638 hardware, namely the @dfn{output volume}, @dfn{monitor volume} and
639 @dfn{input gain}. Finally, you can select which input and output
640 connectors you wish to use.
642 Normally, you configure one unit per sound card. Since most people
643 only have one sound card, all units but unit 0 are often unused.
645 The @samp{Music unit} is the defaults for low-level programs. Such
646 programs often have an audio mode requester that lets you chose an audio
647 mode. If you chose @samp{Default audio mode} from this requester, these
648 settings will be used. Note that the number of channels is not selectable
649 here, it's up to the application program to decide how many channels to
654 @node Advanced settings, , Mode settings, Pages
655 @comment node-name, next, previous, up
656 @subsubsection @samp{Advanced settings} Page
658 @cindex Advanced settings
659 @cindex Settings, advanced
660 @cindex Preferences, advanced
662 This page contains some options that should not be used if you don't
671 Sets the debug level for @sc{Ahi}. If not @samp{None}, @sc{Ahi} will print
672 debug information to the serial port.
674 @cindex Echo, enable/disable/fast
677 On slow processors (like anything below a MC68040) echo can take so much
678 CPU power that it becomes unusable, and can therefore be disabled. As an
679 alternative, echo can be done @samp{Fast}, which means that the parameters
680 will be twisted in order to gain speed. The result may not be what the
681 composer or programmer wanted, but at least it's echo.
683 @cindex Surround sound, enable/disable
685 @item Surround in "Fast" modes
686 In modes that use multiplication tables (the so-called ``fast'' modes) all
687 surround sounds have to be mixing without using tables. In order to make
688 mixing as fast as possible, surround sounds can be forced to ordinary ones
691 @cindex Master volume, clipping
692 @cindex Clipping, master volume
695 Normally, the ``Master volume'' feature of AHI can make the output heavily
696 distorted if set too high. Turning ``clipping'' on can reduce the
697 distortion, but will---in the current implementation---use 128 kB of extra
698 memory. Note that the so-called ``HiFi'' modes are not affected by this
699 switch (@pxref{The Mode Descriptors}).
701 @cindex CPU usage limit
703 @item CPU usage limit
704 Some hardware drivers (but not all) can be told not to use more that a
705 given percentage of the available CPU time in order to prevent lockups. If
706 your mouse pointer freezes when playing music, reduce the limit slightly.
707 If on the other hand the sound becomes cut and distorted, you can try to
708 increase the limit---but remember that you risk locking up the computer!
711 @cindex Default anti-click time
713 @item Default anti-click time
714 Starting with @sc{Ahi} V6, the software mixer can delay the sounds an
715 application wants to play until the currently playing sound goes
716 through a zero-crossing, in order to avoid nasty clicks. Normally,
717 it's the applications job to specify the maximum time the sounds may
718 be delayed, but not all applications provide this information. By
719 setting this slider to the desired value, all applications not
720 specifying their own limit will will default to this value instead.
722 @cindex Volume scaling
725 When more than one application is using @sc{Ahi} at the same time,
726 care has to be taken so no audible distortion is created. In @sc{Ahi}
727 V4 and before, this implied that the volume was lowered in such a way
728 that there were never any distortion. Since ``clipping'' (see above)
729 was optional, this was the only sensible thing to do. In @sc{Ahi} V6,
730 clipping is always used and the distortion created is often not
731 audible. Because of this, all sounds are now played at full volume.
733 However, should you wish so, it's possible to manually select that
734 strategy to use. The available options are @samp{Safe} (as in @sc{Ahi}
735 V4), @samp{Safe, Dynamic} (volume is dynamically adjusted based on how
736 many sounds are curreltly being played), @samp{Full volume} (the new
737 default) and finally @samp{-3 dB} and @samp{-6 dB}, which plays all
738 sounds at -3 or -6 dB.
745 @c ***********************************************************************
746 @c **** AHI-Handler ******************************************************
747 @c ***********************************************************************
749 @node AHI-Handler, System Files, AHI, System description
750 @comment node-name, next, previous, up
754 @cindex @code{AUDIO:}
756 The @code{AHI-Handler} is an I/O mechanism that is used to play and record
757 sounds. The @code{AHI-Handler} is normally mounted as @code{AUDIO:} at
758 startup time, or later by double-clicking on its icon or by giving the
759 following command in a Shell window: @kbd{mount AUDIO: @key{RET}}.
761 The DOSDriver entry is:
765 Handler = L:AHI-Handler
773 When the device is mounted, you can read from the device to record and
774 write to it to play. Options can be given like this:
777 "AUDIO:PRIORITY=1 VOLUME=50"
780 All slashes (@samp{/}) in the name will be translated to spaces. Thus, if
781 you use slashes instead of spaces, you don't have to use quotes around the
785 AUDIO:PRIORITY/1/VOLUME/50
789 The full template for reading is:
792 B=BITS/K/N,@-C=CHANNELS/K/N,@-F=FREQUENCY/K/N,@-T=TYPE/K,@-L=LENGTH/K/N,@-
793 S=SECONDS/K/N,@-BUF=BUFFER/K/N,@-UNIT/K/N
797 The full template for writing is:
800 B=BITS/K/N,@-C=CHANNELS/K/N,@-F=FREQUENCY/K/N,@-T=TYPE/K,@-V=VOLUME/K/N,@-
801 P=POSITION/K/N,@-PRI=PRIORITY/K/N,@-L=LENGTH/K/N,@-S=SECONDS/K/N,@-
802 BUF=BUFFER/K/N,@-UNIT/K/N
805 @samp{BITS} can be one of 8, 16 or 32. @samp{CHANNELS} can be either 1 for
806 mono or 2 for stereo. The @samp{FREQUENCY} is in Hertz, @samp{TYPE} is one
807 of @samp{SIGNED}, @samp{AIFF} or @samp{AIFC}. @samp{VOLUME} ranges from 0
808 (silence) to 100 (full volume), and @samp{POSITION} ranges from @minus{}100
809 (far left) via 0 (center) to 100 (far right). The @samp{PRIORITY} can be
810 from @minus{}128 to 127 (unstoppable). @samp{LENGTH} is how many bytes you
811 wish to read or write, and @samp{SECONDS} is the same, but in seconds
812 instead of bytes. The @samp{BUFFER} size is specified in bytes. Note that
813 two buffers are always used, which means that the memory usage will be two
814 times BUFFER. @samp{UNIT} selects which @code{ahi.device} unit to use.
816 The default options for reading are @samp{BITS=8} @samp{CHANNELS=1}
817 @samp{FREQUENCY=8000} @samp{TYPE=SIGNED} @samp{LENGTH=very-very-much}
818 @samp{BUFFER=32768} @samp{UNIT=0}.
820 The default options for writing are @samp{BITS=8} @samp{CHANNELS=1}
821 @samp{FREQUENCY=8000} @samp{TYPE=<none>} @samp{VOLUME=100}
822 @samp{POSITION=0} @samp{PRIORITY=0} @samp{LENGTH=very-very-much}
823 @samp{BUFFER=32768 UNIT=0}.
830 If @samp{TYPE} is not specified, the default behaviour is to identify the
831 data stream as @dfn{IFF-AIFF} or @dfn{IFF-AIFC}. If so, the default values
832 of @samp{BITS}, @samp{CHANNELS}, @samp{FREQUENCY} and @samp{LENGTH} will
833 taken from the file. You can still override them if you wish. If the
834 stream could not be identified, the data format is assumed to be
837 @cindex Distortion, while recording
839 Both when reading and writing the sample rate will be converted on the fly
840 to what the underlying hardware is configured to. Normally this is not a
841 big problem when writing, but the quality when reading leaves quite a lot
842 to wish for, since no low-pass filters are used.
847 copy Louise.AIFF AUDIO:
850 plays the file @file{Louise.AIFF}.
855 copy AUDIO:SECONDS/10/TYPE/AIFC/B/16/F/44100/C/2 sample.AIFC
858 records 10 seconds of audio and stores it in the file @file{sample.AIFC} as
859 uncompressed @dfn{IFF-AIFC}, 16 bit stereo at 44.1 kHz.
862 @c ***********************************************************************
863 @c **** System Files *****************************************************
864 @c ***********************************************************************
866 @node System Files, , AHI-Handler, System description
867 @comment node-name, next, previous, up
868 @section System Files
873 @cindex Sound card drivers
882 @cindex ForteMedia FM801
888 @cindex SoundBlaster 128
889 @cindex SoundBlaster Live!
891 @cindex Terratec 128i PCI
892 @cindex Terratec 512i digital
897 @sc{Ahi} uses a set of hardware drivers for each sound card. This means
898 that it's easy to add support for new sound cards as they appear. At the
899 time of writing, the following sound cards are supported:
907 Clarity (sampling only)
923 Paula (the built-in audio)
937 Terratec 512i digital
948 * The Mode Descriptors::
952 @node The Drivers, The Mode Descriptors, System Files, System Files
953 @comment node-name, next, previous, up
954 @subsection The Drivers
958 The hardware drivers themself are located in the @file{DEVS:AHI} drawer,
959 and are named as @file{<name>.audio}. They are actually libraries, in
960 spite of being located under the @file{DEVS:} assign, and will be flushed
961 out from memory when not in use and the system needs more RAM. Many of the
962 drivers require additional files; see below. These extra files are not
963 delivered with @sc{Ahi}.
967 @item concierto.audio
968 Requires @code{concierto.library}.
971 Requires @code{delfina.library} version 4 or greater @footnote{The latest
972 version of the Delfina software can be found at Petsoff Limited
973 Partnership's WWW page: @url{http://www.sci.fi/~petsoff}.}.
976 @item maestropro.audio
977 Requires @code{maestix.library} version 40.10 or greater @footnote{
978 @code{maestix.library} is available from AmiNet, for example @*
979 @url{ftp://ftp.germany.aminet.org/pub/aminet/util/libs/Maestix.lha}.}. For
980 more information about this driver as well as the most recent version of
981 @code{maestix.library}, please visit the author's WWW page @footnote{
982 Richard Körber's WWW page: @url{http://www.is-koeln.de/einwohner/shred}.}.
986 Requires @code{melodympeg.device} version 1.40 or greater @footnote{
987 @code{melodympeg.device} and the latest version of this driver can be found
988 at the Kato Development Group's WWW page:
989 @url{http://home.pages.de/~kato}.}.
993 @cindex DAC calibration
994 @cindex 14 bit calibration
995 @cindex Calibration, 14 bit
999 @file{ENV:CyberSound/SoundDrivers/14Bit_Calibration} is read and used
1000 for the 14 bit DAC calibration. This file can be created by using
1001 Christian Buchner's CyberSound calibration tool, which is available
1003 @url{http://www.lysator.liu.se/~lcs/files/ahi/extras/CyberSound.lha},
1006 The 14 bit modes cannot be used for recording, but the 8 bit modes
1007 supports both generic parallel port samplers as well as both the Aura
1008 and Clarity samplers.
1012 The so-called @samp{Paula:DMA 8 bit stereo} mode uses Paula's built-in
1013 DMA engine to play the sounds; no software mixing at all is
1014 performed. Because of this, only four channels are available and no
1015 stereo panning is available (just like all other plain ``stereo''
1016 modes). In addition, the only mixing frequency available is Paula's
1019 @cindex AHIpaulaFilterFreq variable
1021 The environment variable @file{AHIpaulaFilterFreq} is checked every time
1022 playback starts, and should be set to a frequency in Hertz. If the mixing
1023 frequency is higher than this value, the internal low-pass filter will be
1024 turned off. If it is lower, the filter will be activated. The default is
1025 0 Hz, which means that the filter will always be turned off. Example:
1028 SetEnv AHIpaulaFilterFreq 16000
1029 Copy ENV:AHIpaulaFilterFreq ENVARC:
1032 @cindex AHIpaulaSampleLimit variable
1033 @cindex VGA screen mode
1035 The variable @file{AHIpaulaSampleLimit} is also checked. This variable
1036 controls how the driver should handle mixing frequencies greater than 28
1037 kHz, which is the limit of the hardware when using 15 kHz screen modes
1038 (PAL, NTSC, Euro36). If the current screen mode is a VGA (31 kHz) mode,
1039 the driver allows frequencies up to 48 kHz. Normally, the driver checks
1040 the current screen mode, and decides if the higher mixing frequencies
1041 should be available or not. By setting this variable, you can control that
1042 decision. If set to @samp{0}, the frequency will always be limited to 28
1043 kHz and if set to @samp{1}, there will never be any limit. Example:
1046 SetEnv AHIpaulaSampleLimit 1
1047 Copy ENV:AHIpaulaSampleLimit ENVARC:
1050 This will disable any screen mode checking, and will always allow up to 48
1051 kHz in the mode requesters.
1054 Delete ENV:AHIpaulaSampleLimit
1055 Delete ENVARC:AHIpaulaSampleLimit
1058 This will turn on the screen mode checking again.
1061 @cindex AddAudioModes
1063 Please note that this 31 kHz screen mode is not necessary the screen mode
1064 you're seeing on your monitor. If you're using a graphic card, you must
1065 force the Amiga video signal to 31 kHz. CyberGraphX users might want to
1066 try this command (@pxref{AddAudioModes} for more information):
1069 AddAudioModes DBLSCAN
1075 Picasso 96 users just need to set the @file{Picasso96/AmigaVideo} variable
1079 SetEnv Picasso96/AmigaVideo 31kHz
1082 @cindex AHIpaulaSwapChannels variable
1084 Because of incorrect hardware documentation, there is great confusion about
1085 which hardware channels are sent to the left speaker, and which are sent to
1086 the right. @code{paula.audio} uses the correct order (right, left, left,
1087 right) but many other programs don't. The @file{AHIpaulaSwapChannels}
1088 variable was added to let the user decide if the correct or incorrect
1089 behaviour should be used. In not present or set to @samp{0}, the correct
1090 behaviour is used. If set to @samp{1}, the left and right channels will be
1093 @cindex AHIpaulaFakeMixFreq variable
1095 By setting the @file{AHIpaulaFakeMixFreq} variable to @samp{1}, you can make
1096 @code{paula.audio} not report the actual mixing frequency used, but rather
1097 exactly the frequency that the program asked for. The default, @samp{0},
1098 will report the nearest possible mixing frequency that the Paula sound chip
1101 Why would anyone want this, you may ask. Well, by setting the variable
1102 to @samp{1}, you will make @code{paula.audio} behave exactly like
1103 @code{filesave.audio}, which can be important if you are making music that
1104 you will later render and put on a CD, for example. Be warned, however, that
1105 setting this variable to @samp{1} can make the sound produced sound a little
1106 false (but not when rendered, of course)!
1109 @cindex AHIpaulaBufferLength variable
1113 Finally, the variable @file{AHIpaulaBufferLength} controls the minimum
1114 playback buffer size to use. Because of the limited @dfn{Chip RAM}
1115 bandwidth, a @dfn{MC68060} CPU might run into trouble when using the
1116 default minimum buffer size (0). By setting this variable to @samp{1024},
1117 for example, you will reduce the number of interrupts caused and increase
1118 the number of samples transferred each time to at least 1024 samples. But
1119 take care! Setting this variable too high will cause long periods with
1120 multitasking disabled.
1123 @cindex AHItoccataNoTask variable
1126 Requires @code{toccata.library} version 12 or greater @footnote{
1127 @code{toccata.library} is available from AmiNet, for example @*
1128 @url{ftp://ftp.germany.aminet.org/pub/aminet/util/libs/toclib12.lha}.}.
1129 This driver also reads the environment variables @file{AHItoccataNoTask}
1130 and @file{AHItoccataIrqSize}. If @file{AHItoccataNoTask} is set to
1131 @samp{1}, all mixing will be done in a @dfn{Software Interrupt} which means
1132 the sound output will not suffer when multitasking is turned off. The back
1133 side is that it requires a faster CPU. Much faster. Only use this option
1134 as a last resort. Example:
1137 SetEnv AHItoccataNoTask 1
1138 Copy ENV:AHItoccataNoTask ENVARC:
1141 @cindex AHItoccataIrqSize variable
1143 @file{AHItoccataIrqSize} specifies the number of bytes transferred to the
1144 card each interrupt and defaults to @samp{512}. It must be one of
1145 @samp{32}, @samp{64}, @samp{128}, @samp{256} or @samp{512}. If you
1146 encounter problems with serial port hardware, you might want to set this
1147 variable to a lower value than the default.
1149 @cindex AHItoccataPlayBufferSize variable
1151 @file{AHItoccataPlayBufferSize} specifies the number of bytes transferred
1152 to the card when playing and defaults to @samp{512}. It must between 512
1153 and 16384 and also a multiple of 512. If you encounter problems with
1154 serial port hardware, you might want to set this variable to a higher value
1157 @cindex AHItoccataRecordBufferSize variable
1159 @file{AHItoccataRecordBufferSize} specifies the number of bytes transferred
1160 from the card when recording and defaults to @samp{16384}. It must between
1161 512 and 16384 and also a multiple of 512. If you think the latency when
1162 recording is too high, you might want to set this variable to a lower value
1166 Please note that this driver is used for both the DraCo Motion and the
1169 @item wavetools.audio
1170 Requires @code{dad_audio.device}.
1175 @node The Mode Descriptors, , The Drivers, System Files
1176 @comment node-name, next, previous, up
1177 @subsection The Mode Descriptors
1179 @cindex The Mode Descriptors
1180 @cindex Audio mode database
1181 @cindex Database, audio modes
1183 The files in @file{DEVS:AudioModes} describes the available audio modes
1184 that you can chose from in the audio mode requester. All files located in
1185 this drawer will be scanned the first time @sc{Ahi} is used, and added to
1186 the internal mode database.
1188 @cindex Audio modes, overview
1190 The following modes are available for most drivers:
1194 @cindex Mono (audio mode)
1197 Mono output, all sounds will be centered, and no surround sound is
1200 @cindex Stereo (audio mode)
1203 Stereo output, but all sounds are either forces to the extreme left or
1204 extreme right---centered sounds are not possible, for example. This mode
1205 will probably use slightly more CPU power than the ``mono'' mode. Since
1206 all sounds are forced to one of the extreme positions, stereo sounds will
1207 play with either the left or the right part muted.
1209 @cindex Stereo++ (audio mode)
1212 Stereo output with free positioning of all sounds---an instrument can be
1213 placed anywhere between the two speakers, for example. Unless the program
1214 only uses the extremes when positioning a sound, this mode will eat more
1215 CPU cycles than the ``stereo'' mode.
1217 @cindex Fast Mono (audio mode)
1218 @cindex Fast Stereo (audio mode)
1219 @cindex Fast Stereo++ (audio mode)
1220 @cindex Multiplication tables
1221 @cindex Tables, multiplication
1225 @itemx Fast stereo++
1226 ``Fast'' modes take some shortcuts in order to reduce the CPU usage. For 8
1227 bit samples, multiplication tables will be used, which speeds up mixing by
1228 magnitudes and still gives the same quality with the exception of volume
1229 levels---instead of 256 levels only 32 are available. The disadvantage of
1230 multiplication tables is that they require a fair amount of free RAM. For
1231 16 bit samples, the shortcuts are a bit more crude: the volume of each
1232 sound will be rounded to a power of 2 before it's played. This means that
1233 a 16 bit sound will only be played at volume levels of 100%, 50%, 25%,
1234 12.5% etc. If surround sounds are played, the normal (not ``fast'') mixing
1235 routines will be used. You can use the preferences program
1236 (@pxref{Advanced settings}) to disable surround sounds for ``fast'' modes.
1238 ``Fast'' modes are useful if you wish to use as little CPU power as
1239 possible, but don't mind spending some memory to reach that goal. They are
1240 also very useful when playing 16 bit audio streams---from a sample or MPEG
1241 player, for example---since that usually doesn't involve volume scaling
1242 and frequency recalculation. However, if used for playing streams, make
1243 sure the mixing frequency is the same as the stream frequency!
1246 @cindex HiFi Mono (audio mode)
1247 @cindex HiFi Stereo (audio mode)
1248 @cindex HiFi Stereo++ (audio mode)
1249 @cindex Linear interpolation
1250 @cindex Interpolation, linear
1254 @itemx HiFi stereo++
1255 ``HiFi'' modes use much better mixing algorithms than the other modes,
1256 using 32 bits internally and linear interpolation. They are also
1257 @emph{much} slower than the other modes. ``HiFi'' modes turn on master
1258 volume with clipping automatically (@pxref{Advanced settings}).
1260 ``HiFi'' modes are useful when you're playing music---@dfn{MIDI} songs or
1261 @dfn{modules}, for example---and want the best possible quality @sc{Ahi}
1265 @cindex HiFi 7.1 (audio mode)
1268 ``HiFi 7.1'' modes can be used by movie players or audio editors.
1273 @c ***********************************************************************
1274 @c **** The Author *******************************************************
1275 @c ***********************************************************************
1277 @node The Author, Acknowledgments, System description, Top
1278 @comment node-name, next, previous, up
1282 @cindex Author of AHI
1284 The author can be reached at the following addresses:
1288 @item Electronic mail
1289 @email{martin@@blom.org}
1294 @*SE-587 34 Linköping
1297 @item World-Wide Web
1298 @url{http://martin.blom.org}
1309 @c ***********************************************************************
1310 @c **** The Man **********************************************************
1311 @c ***********************************************************************
1313 @node The Man, The Myth, The Author, The Author
1314 @comment node-name, next, previous, up
1318 @cindex Nerd, definition of
1320 Martin Blom was born 1974 in a town in Sweden called Jönköping. He had a
1321 happy childhood, lots of good friends, and a great family. He did his
1322 homework and went to church every Sunday.
1324 @cindex Jesus Christ
1326 But then, one cold, dark Christmas Eve in the year of our Lord 1986,
1327 everything went wrong. This was the day when @emph{it} entered his life.
1328 At once, there were fights among the brothers. They all wanted to use
1329 @emph{it}. Martin started to avoid playing with kids that didn't share his
1330 passion for @emph{it}. The school work suffered. Other interests
1331 suffered. @emph{It} was the Commodore 64 home computer, and it would
1332 forever change his life.
1334 Today, more than ten years after the tragedy, things are worse than ever.
1335 He is studying @dfn{Computer Science and Engineering} at @dfn{Linköping
1336 Institute of Technology}, surrounded every day by other computer nerds.
1338 @cindex Modules on a C64
1340 Martin has spent loads of money on computers over the years: Amiga 500,
1341 Amiga 4000/040, Commodore 128D, Commodore 64 (in order of appearance),
1342 modem, monitors, disks, mice etc. Interesting enough, no sound card. He
1343 did, however, build a sound card of his own for the Commodore 64, and he
1344 likes to mention that now and then (you see, this was one of the few
1345 hardware projects that actually worked!). 4 channels, 8 bit samples. He
1346 even wrote a module player for the good old 64. And it had quadrascopes.
1350 @c ***********************************************************************
1351 @c **** The Myth *********************************************************
1352 @c ***********************************************************************
1354 @node The Myth, The Concept, The Man, The Author
1355 @comment node-name, next, previous, up
1360 Some people actually seem to believe that Martin is a good programmer.
1361 They couldn't be more wrong. He is lazy, has no patience, he is a slow
1362 thinker and he doesn't like anything he @emph{has} to do.
1368 If you can't write applications, write games.
1370 If you can't write games, write demos.
1372 If you can't write demos, write utilities.
1374 If you can't write utilities, write BBS intros and doors.
1376 If you can't do that either, get a modem and start trading.
1380 And guess what? He tried demos. He tried utilities. He tried intros. He
1381 wrote a door for /X. And he traded warez.
1384 @c ***********************************************************************
1385 @c **** The Concept ******************************************************
1386 @c ***********************************************************************
1388 @node The Concept, , The Myth, The Author
1389 @comment node-name, next, previous, up
1390 @section The Concept
1395 What do you do if you don't have the patience to write applications, if you
1396 only write moderate demos, are tired of utilities, hate BBS doors, are
1397 totally fed up with playing games and have decided to get legal and stop
1398 pirating software? Simple. Try a new concept!
1400 Take a deep breath. Close your eyes. Think of one thing your computer
1401 lacks. Think of one of the things that makes your favorite toy feel
1402 outdated. Think of something that nobody has (successfully) tried before.
1403 Then write the software, and release it as Freeware.
1405 In Martins case, that something was hardware independent audio.
1407 Come on, admit it! It's brilliant. It doesn't matter if you are a good
1408 programmer. It doesn't matter if it takes 3 years to get to a
1409 half-finished product. It doesn't matter if you give it the most
1410 unimaginative name in the world---you can even use a TLA @footnote{Three
1411 Letter Acronym}. Nobody is going to say your software sucks, because
1412 nobody can say he has done better himself. Nobody is going to complain if
1413 you're slow on releasing bug fixes and updates, because the software is
1414 free. And nobody is going to be angry with you if you stop developing the
1415 software---because it sucked in the first place, remember?
1417 This concept won't make you rich, but are rich people really happier?
1420 @c ***********************************************************************
1421 @c **** Acknowledgments *************************************************
1422 @c ***********************************************************************
1424 @node Acknowledgments, GPL, The Author, Top
1425 @comment node-name, next, previous, up
1426 @chapter Acknowledgments
1428 @cindex Acknowledgments
1430 There are quite a few people that have helped with the development of
1431 @sc{Ahi}. Where would be a better place to thank them than in the
1432 acknowledgments chapter? You tell me.
1438 * Honourable mention::
1441 If you feel your name ought to be present here, please accept my
1442 apologies and don't hesitate to contact me as soon as possible.
1445 @c ***********************************************************************
1446 @c **** Special thanks ***************************************************
1447 @c ***********************************************************************
1449 @node Thanks, Contributors, Acknowledgments, Acknowledgments
1450 @comment node-name, next, previous, up
1451 @section Special thanks
1453 @cindex Special thanks
1455 The author wish to give special thanks to the following persons
1456 (in alphabetical order):
1460 @item Amiga Translators' Organization
1461 For the catalog translations.
1463 @item Daniel Arthursson and Johan Nyblom
1464 For making it possible to write the first driver for a sound card, the
1465 @dfn{Wavetools} card. I'm sure @sc{Ahi} would not have been accepted as
1466 quick as it was without this driver.
1468 @item Christian Buchner
1469 For the calibrated 14 bit routines for Paula.
1471 @item MacroSystem Computer GmbH
1472 For lending me a Toccata card.
1474 @item bbrv and Genesi
1475 For the Pegasos and that cool OS.
1477 @item Przemyslaw Gruchala
1478 For finding all those bugs.
1480 @item Ben Hermans and Hyperion Entertainment
1481 For hiring me to write a SBLive! driver.
1483 @item Steve Krueger and SAS Institute, Inc.
1484 For the SAS/C compiler and all the updates.
1486 @item Johan Otterström
1487 For all the help with the Toccata driver.
1489 @item Jyrki Petsalo and Teemu Suikki
1490 For the Delfina driver, and for supporting @sc{Ahi} in the early days. And
1491 of course, for the sound card!
1494 For active support and promotion of @sc{Ahi} from the beginning.
1497 Many, many other have helped me, sent suggestions etc. I owe you a lot.
1501 And of course, the actual catalog translators:
1503 Andrija Antonijevic,
1526 me, myself and I@enddots{}
1529 @c ***********************************************************************
1530 @c **** Contributors *****************************************************
1531 @c ***********************************************************************
1533 @node Contributors, Donors, Thanks, Acknowledgments
1534 @comment node-name, next, previous, up
1535 @section Contributors
1537 @cindex Contributors
1539 The following people have contributed to the @sc{Ahi} project with
1544 @item Stéphane Barbaray
1545 The MUI version of the preferences program.
1548 The Concierto driver.
1551 A (never finished?) Sunrize driver.
1553 @item Valenta Ferenc
1557 A never finished Sunrize driver. May he rest in peace.
1559 @item Simon N Goodwin
1560 A good attempt on the Silicon Studio driver. :-)
1562 @item Przemyslaw Gruchala
1563 A C-Media and a Yet To Be Named driver. :-)
1565 @item Thorsten Hansen
1566 The Melody MPEG and Amithlon drivers.
1568 @item Richard Körber
1569 The Maestro Pro driver.
1572 The GREX and Pegasos drivers.
1574 @item Bernd `Bernie' Meyer
1575 The---sniff!---never to be released Umilator driver.
1580 @item Kenneth Nilsen
1581 A (never finished?) Sunrize driver. And here I was, thinking the
1582 ``Amiga'' curse was the worst curse of them all @enddots{}
1585 The latest Wavetools driver.
1588 The first version of the Toccata driver.
1590 @item Markus Pöllmann
1596 @item Harry Sintonen
1597 The very first source code patch!
1599 @item Sigbjørn Skjæret
1600 A 'C' version of @code{paula.audio}.
1602 @item Stefan Sommerfeld
1606 The first version of the preferences program. Too bad things didn't work
1610 The Mediator drivers.
1613 The Delfina driver and the first PPC port.
1615 @item Benjamin Vernoux
1619 The AmigaOS 4.x port and many drivers.
1625 The (no longer used) ELF loader.
1631 @c ***********************************************************************
1632 @c **** Donors ***********************************************************
1633 @c ***********************************************************************
1635 @node Donors, Honourable mention, Contributors, Acknowledgments
1636 @comment node-name, next, previous, up
1639 The following people has donated money to the project. It has ment a
1640 lot to me, and please forgive me for not being able to finish a
1641 working WarpUp or PowerUp PPC version of @sc{Ahi}. I hope the MorphOS
1642 and upcoming AmigaOS 4 versions made up for that.
1651 Christopher Lakatos,
1654 Fredrik Westermarck,
1679 Robert Korzeniewski,
1686 Thomas & Stefan Lorenz,
1694 @c ***********************************************************************
1695 @c **** Honourable mention ***********************************************
1696 @c ***********************************************************************
1698 @node Honourable mention, , Donors, Acknowledgments
1699 @comment node-name, next, previous, up
1700 @section Honourable mention
1702 @cindex Honourable mention
1704 The road from @sc{Ahi} version 4 to version 6 has been a long one.
1705 Maybe not when counted in actual work hours, but definitely when
1706 counted in calendar time.
1708 It began with a failed attempt to port the device to the PowerPC
1709 processor, at which time @sc{Ahi} became a ``shareware'' product in
1710 order to finance a Cyberstorm/PPC CPU card (@pxref{Donors}). When I
1711 realized I couldn't deliver, @sc{Ahi} instead became Free Software,
1712 which it still and will probably always be.
1714 The first release of the source code under the ``GPL'' was made on
1715 April 1st, 1999, as part of the ``Divine Records'' joke (see
1716 @url{http://martin.blom.org/ds/} and
1717 @url{http://martin.blom.org/dr/}@footnote{Believe it or not, but I
1718 still get mail from people who want me to publish their music now and
1721 Some people actually took their time to fill in the source code
1722 registration form. You know who you are. Thank you! I'm sure I'll
1723 figure out what to do will all addresses real soon now.
1725 But here comes the best part: Benoit Deschenes (Quebec, Canada),
1726 Thomas Houlberg (Sdr. Bjert, Denmark) and Patrice Machin (Paris,
1727 France) actually ordered my CD. Unfortunately, I only made a limited
1728 amount of those CDs (17 plus one pre-production CD, if I remember
1729 correctly) and have been out of stock ever since. To compensate for
1730 this unusually long delivery delay, I've decided to try to produce
1731 three extra copies and send them to you for free. Benoit, Thomas and
1732 Patrice, if you read this and have moved since 1999, please let me
1733 know of your new address as soon as possible!
1736 @c ***********************************************************************
1737 @c **** GNU General Public License ***************************************
1738 @c ***********************************************************************
1740 @node GPL, LGPL, Acknowledgments, Top
1741 @comment node-name, next, previous, up
1742 @unnumbered GNU GENERAL PUBLIC LICENSE
1743 @center Version 2, June 1991
1746 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
1747 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
1749 Everyone is permitted to copy and distribute verbatim copies
1750 of this license document, but changing it is not allowed.
1753 @unnumberedsec Preamble
1755 The licenses for most software are designed to take away your
1756 freedom to share and change it. By contrast, the GNU General Public
1757 License is intended to guarantee your freedom to share and change free
1758 software---to make sure the software is free for all its users. This
1759 General Public License applies to most of the Free Software
1760 Foundation's software and to any other program whose authors commit to
1761 using it. (Some other Free Software Foundation software is covered by
1762 the GNU Library General Public License instead.) You can apply it to
1765 When we speak of free software, we are referring to freedom, not
1766 price. Our General Public Licenses are designed to make sure that you
1767 have the freedom to distribute copies of free software (and charge for
1768 this service if you wish), that you receive source code or can get it
1769 if you want it, that you can change the software or use pieces of it
1770 in new free programs; and that you know you can do these things.
1772 To protect your rights, we need to make restrictions that forbid
1773 anyone to deny you these rights or to ask you to surrender the rights.
1774 These restrictions translate to certain responsibilities for you if you
1775 distribute copies of the software, or if you modify it.
1777 For example, if you distribute copies of such a program, whether
1778 gratis or for a fee, you must give the recipients all the rights that
1779 you have. You must make sure that they, too, receive or can get the
1780 source code. And you must show them these terms so they know their
1783 We protect your rights with two steps: (1) copyright the software, and
1784 (2) offer you this license which gives you legal permission to copy,
1785 distribute and/or modify the software.
1787 Also, for each author's protection and ours, we want to make certain
1788 that everyone understands that there is no warranty for this free
1789 software. If the software is modified by someone else and passed on, we
1790 want its recipients to know that what they have is not the original, so
1791 that any problems introduced by others will not reflect on the original
1792 authors' reputations.
1794 Finally, any free program is threatened constantly by software
1795 patents. We wish to avoid the danger that redistributors of a free
1796 program will individually obtain patent licenses, in effect making the
1797 program proprietary. To prevent this, we have made it clear that any
1798 patent must be licensed for everyone's free use or not licensed at all.
1800 The precise terms and conditions for copying, distribution and
1801 modification follow.
1804 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
1807 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
1812 This License applies to any program or other work which contains
1813 a notice placed by the copyright holder saying it may be distributed
1814 under the terms of this General Public License. The ``Program'', below,
1815 refers to any such program or work, and a ``work based on the Program''
1816 means either the Program or any derivative work under copyright law:
1817 that is to say, a work containing the Program or a portion of it,
1818 either verbatim or with modifications and/or translated into another
1819 language. (Hereinafter, translation is included without limitation in
1820 the term ``modification''.) Each licensee is addressed as ``you''.
1822 Activities other than copying, distribution and modification are not
1823 covered by this License; they are outside its scope. The act of
1824 running the Program is not restricted, and the output from the Program
1825 is covered only if its contents constitute a work based on the
1826 Program (independent of having been made by running the Program).
1827 Whether that is true depends on what the Program does.
1830 You may copy and distribute verbatim copies of the Program's
1831 source code as you receive it, in any medium, provided that you
1832 conspicuously and appropriately publish on each copy an appropriate
1833 copyright notice and disclaimer of warranty; keep intact all the
1834 notices that refer to this License and to the absence of any warranty;
1835 and give any other recipients of the Program a copy of this License
1836 along with the Program.
1838 You may charge a fee for the physical act of transferring a copy, and
1839 you may at your option offer warranty protection in exchange for a fee.
1842 You may modify your copy or copies of the Program or any portion
1843 of it, thus forming a work based on the Program, and copy and
1844 distribute such modifications or work under the terms of Section 1
1845 above, provided that you also meet all of these conditions:
1849 You must cause the modified files to carry prominent notices
1850 stating that you changed the files and the date of any change.
1853 You must cause any work that you distribute or publish, that in
1854 whole or in part contains or is derived from the Program or any
1855 part thereof, to be licensed as a whole at no charge to all third
1856 parties under the terms of this License.
1859 If the modified program normally reads commands interactively
1860 when run, you must cause it, when started running for such
1861 interactive use in the most ordinary way, to print or display an
1862 announcement including an appropriate copyright notice and a
1863 notice that there is no warranty (or else, saying that you provide
1864 a warranty) and that users may redistribute the program under
1865 these conditions, and telling the user how to view a copy of this
1866 License. (Exception: if the Program itself is interactive but
1867 does not normally print such an announcement, your work based on
1868 the Program is not required to print an announcement.)
1871 These requirements apply to the modified work as a whole. If
1872 identifiable sections of that work are not derived from the Program,
1873 and can be reasonably considered independent and separate works in
1874 themselves, then this License, and its terms, do not apply to those
1875 sections when you distribute them as separate works. But when you
1876 distribute the same sections as part of a whole which is a work based
1877 on the Program, the distribution of the whole must be on the terms of
1878 this License, whose permissions for other licensees extend to the
1879 entire whole, and thus to each and every part regardless of who wrote it.
1881 Thus, it is not the intent of this section to claim rights or contest
1882 your rights to work written entirely by you; rather, the intent is to
1883 exercise the right to control the distribution of derivative or
1884 collective works based on the Program.
1886 In addition, mere aggregation of another work not based on the Program
1887 with the Program (or with a work based on the Program) on a volume of
1888 a storage or distribution medium does not bring the other work under
1889 the scope of this License.
1892 You may copy and distribute the Program (or a work based on it,
1893 under Section 2) in object code or executable form under the terms of
1894 Sections 1 and 2 above provided that you also do one of the following:
1898 Accompany it with the complete corresponding machine-readable
1899 source code, which must be distributed under the terms of Sections
1900 1 and 2 above on a medium customarily used for software interchange; or,
1903 Accompany it with a written offer, valid for at least three
1904 years, to give any third party, for a charge no more than your
1905 cost of physically performing source distribution, a complete
1906 machine-readable copy of the corresponding source code, to be
1907 distributed under the terms of Sections 1 and 2 above on a medium
1908 customarily used for software interchange; or,
1911 Accompany it with the information you received as to the offer
1912 to distribute corresponding source code. (This alternative is
1913 allowed only for noncommercial distribution and only if you
1914 received the program in object code or executable form with such
1915 an offer, in accord with Subsection b above.)
1918 The source code for a work means the preferred form of the work for
1919 making modifications to it. For an executable work, complete source
1920 code means all the source code for all modules it contains, plus any
1921 associated interface definition files, plus the scripts used to
1922 control compilation and installation of the executable. However, as a
1923 special exception, the source code distributed need not include
1924 anything that is normally distributed (in either source or binary
1925 form) with the major components (compiler, kernel, and so on) of the
1926 operating system on which the executable runs, unless that component
1927 itself accompanies the executable.
1929 If distribution of executable or object code is made by offering
1930 access to copy from a designated place, then offering equivalent
1931 access to copy the source code from the same place counts as
1932 distribution of the source code, even though third parties are not
1933 compelled to copy the source along with the object code.
1936 You may not copy, modify, sublicense, or distribute the Program
1937 except as expressly provided under this License. Any attempt
1938 otherwise to copy, modify, sublicense or distribute the Program is
1939 void, and will automatically terminate your rights under this License.
1940 However, parties who have received copies, or rights, from you under
1941 this License will not have their licenses terminated so long as such
1942 parties remain in full compliance.
1945 You are not required to accept this License, since you have not
1946 signed it. However, nothing else grants you permission to modify or
1947 distribute the Program or its derivative works. These actions are
1948 prohibited by law if you do not accept this License. Therefore, by
1949 modifying or distributing the Program (or any work based on the
1950 Program), you indicate your acceptance of this License to do so, and
1951 all its terms and conditions for copying, distributing or modifying
1952 the Program or works based on it.
1955 Each time you redistribute the Program (or any work based on the
1956 Program), the recipient automatically receives a license from the
1957 original licensor to copy, distribute or modify the Program subject to
1958 these terms and conditions. You may not impose any further
1959 restrictions on the recipients' exercise of the rights granted herein.
1960 You are not responsible for enforcing compliance by third parties to
1964 If, as a consequence of a court judgment or allegation of patent
1965 infringement or for any other reason (not limited to patent issues),
1966 conditions are imposed on you (whether by court order, agreement or
1967 otherwise) that contradict the conditions of this License, they do not
1968 excuse you from the conditions of this License. If you cannot
1969 distribute so as to satisfy simultaneously your obligations under this
1970 License and any other pertinent obligations, then as a consequence you
1971 may not distribute the Program at all. For example, if a patent
1972 license would not permit royalty-free redistribution of the Program by
1973 all those who receive copies directly or indirectly through you, then
1974 the only way you could satisfy both it and this License would be to
1975 refrain entirely from distribution of the Program.
1977 If any portion of this section is held invalid or unenforceable under
1978 any particular circumstance, the balance of the section is intended to
1979 apply and the section as a whole is intended to apply in other
1982 It is not the purpose of this section to induce you to infringe any
1983 patents or other property right claims or to contest validity of any
1984 such claims; this section has the sole purpose of protecting the
1985 integrity of the free software distribution system, which is
1986 implemented by public license practices. Many people have made
1987 generous contributions to the wide range of software distributed
1988 through that system in reliance on consistent application of that
1989 system; it is up to the author/donor to decide if he or she is willing
1990 to distribute software through any other system and a licensee cannot
1993 This section is intended to make thoroughly clear what is believed to
1994 be a consequence of the rest of this License.
1997 If the distribution and/or use of the Program is restricted in
1998 certain countries either by patents or by copyrighted interfaces, the
1999 original copyright holder who places the Program under this License
2000 may add an explicit geographical distribution limitation excluding
2001 those countries, so that distribution is permitted only in or among
2002 countries not thus excluded. In such case, this License incorporates
2003 the limitation as if written in the body of this License.
2006 The Free Software Foundation may publish revised and/or new versions
2007 of the General Public License from time to time. Such new versions will
2008 be similar in spirit to the present version, but may differ in detail to
2009 address new problems or concerns.
2011 Each version is given a distinguishing version number. If the Program
2012 specifies a version number of this License which applies to it and ``any
2013 later version'', you have the option of following the terms and conditions
2014 either of that version or of any later version published by the Free
2015 Software Foundation. If the Program does not specify a version number of
2016 this License, you may choose any version ever published by the Free Software
2020 If you wish to incorporate parts of the Program into other free
2021 programs whose distribution conditions are different, write to the author
2022 to ask for permission. For software which is copyrighted by the Free
2023 Software Foundation, write to the Free Software Foundation; we sometimes
2024 make exceptions for this. Our decision will be guided by the two goals
2025 of preserving the free status of all derivatives of our free software and
2026 of promoting the sharing and reuse of software generally.
2029 @heading NO WARRANTY
2036 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
2037 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN
2038 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
2039 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
2040 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
2041 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@. THE ENTIRE RISK AS
2042 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU@. SHOULD THE
2043 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
2044 REPAIR OR CORRECTION.
2047 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
2048 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
2049 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
2050 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
2051 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
2052 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
2053 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
2054 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
2055 POSSIBILITY OF SUCH DAMAGES.
2059 @heading END OF TERMS AND CONDITIONS
2062 @center END OF TERMS AND CONDITIONS
2066 @unnumberedsec How to Apply These Terms to Your New Programs
2068 If you develop a new program, and you want it to be of the greatest
2069 possible use to the public, the best way to achieve this is to make it
2070 free software which everyone can redistribute and change under these terms.
2072 To do so, attach the following notices to the program. It is safest
2073 to attach them to the start of each source file to most effectively
2074 convey the exclusion of warranty; and each file should have at least
2075 the ``copyright'' line and a pointer to where the full notice is found.
2078 @var{one line to give the program's name and an idea of what it does.}
2079 Copyright (C) 19@var{yy} @var{name of author}
2081 This program is free software; you can redistribute it and/or
2082 modify it under the terms of the GNU General Public License
2083 as published by the Free Software Foundation; either version 2
2084 of the License, or (at your option) any later version.
2086 This program is distributed in the hope that it will be useful,
2087 but WITHOUT ANY WARRANTY; without even the implied warranty of
2088 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the
2089 GNU General Public License for more details.
2091 You should have received a copy of the GNU General Public License along
2092 with this program; if not, write to the Free Software Foundation, Inc.,
2093 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
2096 Also add information on how to contact you by electronic and paper mail.
2098 If the program is interactive, make it output a short notice like this
2099 when it starts in an interactive mode:
2102 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
2103 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
2104 type `show w'. This is free software, and you are welcome
2105 to redistribute it under certain conditions; type `show c'
2109 The hypothetical commands @samp{show w} and @samp{show c} should show
2110 the appropriate parts of the General Public License. Of course, the
2111 commands you use may be called something other than @samp{show w} and
2112 @samp{show c}; they could even be mouse-clicks or menu items---whatever
2115 You should also get your employer (if you work as a programmer) or your
2116 school, if any, to sign a ``copyright disclaimer'' for the program, if
2117 necessary. Here is a sample; alter the names:
2121 Yoyodyne, Inc., hereby disclaims all copyright
2122 interest in the program `Gnomovision'
2123 (which makes passes at compilers) written
2126 @var{signature of Ty Coon}, 1 April 1989
2127 Ty Coon, President of Vice
2131 This General Public License does not permit incorporating your program into
2132 proprietary programs. If your program is a subroutine library, you may
2133 consider it more useful to permit linking proprietary applications with the
2134 library. If this is what you want to do, use the GNU Library General
2135 Public License instead of this License.
2137 @c ***********************************************************************
2138 @c **** GNU Library General Public License *******************************
2139 @c ***********************************************************************
2141 @node LGPL, Concept Index, GPL, Top
2142 @comment node-name, next, previous, up
2143 @unnumbered GNU LIBRARY GENERAL PUBLIC LICENSE
2145 @center Version 2, June 1991
2148 Copyright @copyright{} 1991 Free Software Foundation, Inc.
2149 675 Mass Ave, Cambridge, MA 02139, USA
2150 Everyone is permitted to copy and distribute verbatim copies
2151 of this license document, but changing it is not allowed.
2153 [This is the first released version of the library GPL. It is
2154 numbered 2 because it goes with version 2 of the ordinary GPL.]
2157 @unnumberedsec Preamble
2159 The licenses for most software are designed to take away your
2160 freedom to share and change it. By contrast, the GNU General Public
2161 Licenses are intended to guarantee your freedom to share and change
2162 free software---to make sure the software is free for all its users.
2164 This license, the Library General Public License, applies to some
2165 specially designated Free Software Foundation software, and to any
2166 other libraries whose authors decide to use it. You can use it for
2167 your libraries, too.
2169 When we speak of free software, we are referring to freedom, not
2170 price. Our General Public Licenses are designed to make sure that you
2171 have the freedom to distribute copies of free software (and charge for
2172 this service if you wish), that you receive source code or can get it
2173 if you want it, that you can change the software or use pieces of it
2174 in new free programs; and that you know you can do these things.
2176 To protect your rights, we need to make restrictions that forbid
2177 anyone to deny you these rights or to ask you to surrender the rights.
2178 These restrictions translate to certain responsibilities for you if
2179 you distribute copies of the library, or if you modify it.
2181 For example, if you distribute copies of the library, whether gratis
2182 or for a fee, you must give the recipients all the rights that we gave
2183 you. You must make sure that they, too, receive or can get the source
2184 code. If you link a program with the library, you must provide
2185 complete object files to the recipients so that they can relink them
2186 with the library, after making changes to the library and recompiling
2187 it. And you must show them these terms so they know their rights.
2189 Our method of protecting your rights has two steps: (1) copyright
2190 the library, and (2) offer you this license which gives you legal
2191 permission to copy, distribute and/or modify the library.
2193 Also, for each distributor's protection, we want to make certain
2194 that everyone understands that there is no warranty for this free
2195 library. If the library is modified by someone else and passed on, we
2196 want its recipients to know that what they have is not the original
2197 version, so that any problems introduced by others will not reflect on
2198 the original authors' reputations.
2200 Finally, any free program is threatened constantly by software
2201 patents. We wish to avoid the danger that companies distributing free
2202 software will individually obtain patent licenses, thus in effect
2203 transforming the program into proprietary software. To prevent this,
2204 we have made it clear that any patent must be licensed for everyone's
2205 free use or not licensed at all.
2207 Most GNU software, including some libraries, is covered by the ordinary
2208 GNU General Public License, which was designed for utility programs. This
2209 license, the GNU Library General Public License, applies to certain
2210 designated libraries. This license is quite different from the ordinary
2211 one; be sure to read it in full, and don't assume that anything in it is
2212 the same as in the ordinary license.
2214 The reason we have a separate public license for some libraries is that
2215 they blur the distinction we usually make between modifying or adding to a
2216 program and simply using it. Linking a program with a library, without
2217 changing the library, is in some sense simply using the library, and is
2218 analogous to running a utility program or application program. However, in
2219 a textual and legal sense, the linked executable is a combined work, a
2220 derivative of the original library, and the ordinary General Public License
2223 Because of this blurred distinction, using the ordinary General
2224 Public License for libraries did not effectively promote software
2225 sharing, because most developers did not use the libraries. We
2226 concluded that weaker conditions might promote sharing better.
2228 However, unrestricted linking of non-free programs would deprive the
2229 users of those programs of all benefit from the free status of the
2230 libraries themselves. This Library General Public License is intended to
2231 permit developers of non-free programs to use free libraries, while
2232 preserving your freedom as a user of such programs to change the free
2233 libraries that are incorporated in them. (We have not seen how to achieve
2234 this as regards changes in header files, but we have achieved it as regards
2235 changes in the actual functions of the Library.) The hope is that this
2236 will lead to faster development of free libraries.
2238 The precise terms and conditions for copying, distribution and
2239 modification follow. Pay close attention to the difference between a
2240 ``work based on the library'' and a ``work that uses the library''. The
2241 former contains code derived from the library, while the latter only
2242 works together with the library.
2244 Note that it is possible for a library to be covered by the ordinary
2245 General Public License rather than by this special one.
2248 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2251 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2256 This License Agreement applies to any software library which
2257 contains a notice placed by the copyright holder or other authorized
2258 party saying it may be distributed under the terms of this Library
2259 General Public License (also called ``this License''). Each licensee is
2260 addressed as ``you''.
2262 A ``library'' means a collection of software functions and/or data
2263 prepared so as to be conveniently linked with application programs
2264 (which use some of those functions and data) to form executables.
2266 The ``Library'', below, refers to any such software library or work
2267 which has been distributed under these terms. A ``work based on the
2268 Library'' means either the Library or any derivative work under
2269 copyright law: that is to say, a work containing the Library or a
2270 portion of it, either verbatim or with modifications and/or translated
2271 straightforwardly into another language. (Hereinafter, translation is
2272 included without limitation in the term ``modification''.)
2274 ``Source code'' for a work means the preferred form of the work for
2275 making modifications to it. For a library, complete source code means
2276 all the source code for all modules it contains, plus any associated
2277 interface definition files, plus the scripts used to control compilation
2278 and installation of the library.
2280 Activities other than copying, distribution and modification are not
2281 covered by this License; they are outside its scope. The act of
2282 running a program using the Library is not restricted, and output from
2283 such a program is covered only if its contents constitute a work based
2284 on the Library (independent of the use of the Library in a tool for
2285 writing it). Whether that is true depends on what the Library does
2286 and what the program that uses the Library does.
2289 You may copy and distribute verbatim copies of the Library's
2290 complete source code as you receive it, in any medium, provided that
2291 you conspicuously and appropriately publish on each copy an
2292 appropriate copyright notice and disclaimer of warranty; keep intact
2293 all the notices that refer to this License and to the absence of any
2294 warranty; and distribute a copy of this License along with the
2297 You may charge a fee for the physical act of transferring a copy,
2298 and you may at your option offer warranty protection in exchange for a
2302 You may modify your copy or copies of the Library or any portion
2303 of it, thus forming a work based on the Library, and copy and
2304 distribute such modifications or work under the terms of Section 1
2305 above, provided that you also meet all of these conditions:
2309 The modified work must itself be a software library.
2312 You must cause the files modified to carry prominent notices
2313 stating that you changed the files and the date of any change.
2316 You must cause the whole of the work to be licensed at no
2317 charge to all third parties under the terms of this License.
2320 If a facility in the modified Library refers to a function or a
2321 table of data to be supplied by an application program that uses
2322 the facility, other than as an argument passed when the facility
2323 is invoked, then you must make a good faith effort to ensure that,
2324 in the event an application does not supply such function or
2325 table, the facility still operates, and performs whatever part of
2326 its purpose remains meaningful.
2328 (For example, a function in a library to compute square roots has
2329 a purpose that is entirely well-defined independent of the
2330 application. Therefore, Subsection 2d requires that any
2331 application-supplied function or table used by this function must
2332 be optional: if the application does not supply it, the square
2333 root function must still compute square roots.)
2336 These requirements apply to the modified work as a whole. If
2337 identifiable sections of that work are not derived from the Library,
2338 and can be reasonably considered independent and separate works in
2339 themselves, then this License, and its terms, do not apply to those
2340 sections when you distribute them as separate works. But when you
2341 distribute the same sections as part of a whole which is a work based
2342 on the Library, the distribution of the whole must be on the terms of
2343 this License, whose permissions for other licensees extend to the
2344 entire whole, and thus to each and every part regardless of who wrote
2347 Thus, it is not the intent of this section to claim rights or contest
2348 your rights to work written entirely by you; rather, the intent is to
2349 exercise the right to control the distribution of derivative or
2350 collective works based on the Library.
2352 In addition, mere aggregation of another work not based on the Library
2353 with the Library (or with a work based on the Library) on a volume of
2354 a storage or distribution medium does not bring the other work under
2355 the scope of this License.
2358 You may opt to apply the terms of the ordinary GNU General Public
2359 License instead of this License to a given copy of the Library. To do
2360 this, you must alter all the notices that refer to this License, so
2361 that they refer to the ordinary GNU General Public License, version 2,
2362 instead of to this License. (If a newer version than version 2 of the
2363 ordinary GNU General Public License has appeared, then you can specify
2364 that version instead if you wish.) Do not make any other change in
2367 Once this change is made in a given copy, it is irreversible for
2368 that copy, so the ordinary GNU General Public License applies to all
2369 subsequent copies and derivative works made from that copy.
2371 This option is useful when you wish to copy part of the code of
2372 the Library into a program that is not a library.
2375 You may copy and distribute the Library (or a portion or
2376 derivative of it, under Section 2) in object code or executable form
2377 under the terms of Sections 1 and 2 above provided that you accompany
2378 it with the complete corresponding machine-readable source code, which
2379 must be distributed under the terms of Sections 1 and 2 above on a
2380 medium customarily used for software interchange.
2382 If distribution of object code is made by offering access to copy
2383 from a designated place, then offering equivalent access to copy the
2384 source code from the same place satisfies the requirement to
2385 distribute the source code, even though third parties are not
2386 compelled to copy the source along with the object code.
2389 A program that contains no derivative of any portion of the
2390 Library, but is designed to work with the Library by being compiled or
2391 linked with it, is called a ``work that uses the Library''. Such a
2392 work, in isolation, is not a derivative work of the Library, and
2393 therefore falls outside the scope of this License.
2395 However, linking a ``work that uses the Library'' with the Library
2396 creates an executable that is a derivative of the Library (because it
2397 contains portions of the Library), rather than a ``work that uses the
2398 library''. The executable is therefore covered by this License.
2399 Section 6 states terms for distribution of such executables.
2401 When a ``work that uses the Library'' uses material from a header file
2402 that is part of the Library, the object code for the work may be a
2403 derivative work of the Library even though the source code is not.
2404 Whether this is true is especially significant if the work can be
2405 linked without the Library, or if the work is itself a library. The
2406 threshold for this to be true is not precisely defined by law.
2408 If such an object file uses only numerical parameters, data
2409 structure layouts and accessors, and small macros and small inline
2410 functions (ten lines or less in length), then the use of the object
2411 file is unrestricted, regardless of whether it is legally a derivative
2412 work. (Executables containing this object code plus portions of the
2413 Library will still fall under Section 6.)
2415 Otherwise, if the work is a derivative of the Library, you may
2416 distribute the object code for the work under the terms of Section 6.
2417 Any executables containing that work also fall under Section 6,
2418 whether or not they are linked directly with the Library itself.
2421 As an exception to the Sections above, you may also compile or
2422 link a ``work that uses the Library'' with the Library to produce a
2423 work containing portions of the Library, and distribute that work
2424 under terms of your choice, provided that the terms permit
2425 modification of the work for the customer's own use and reverse
2426 engineering for debugging such modifications.
2428 You must give prominent notice with each copy of the work that the
2429 Library is used in it and that the Library and its use are covered by
2430 this License. You must supply a copy of this License. If the work
2431 during execution displays copyright notices, you must include the
2432 copyright notice for the Library among them, as well as a reference
2433 directing the user to the copy of this License. Also, you must do one
2438 Accompany the work with the complete corresponding
2439 machine-readable source code for the Library including whatever
2440 changes were used in the work (which must be distributed under
2441 Sections 1 and 2 above); and, if the work is an executable linked
2442 with the Library, with the complete machine-readable ``work that
2443 uses the Library'', as object code and/or source code, so that the
2444 user can modify the Library and then relink to produce a modified
2445 executable containing the modified Library. (It is understood
2446 that the user who changes the contents of definitions files in the
2447 Library will not necessarily be able to recompile the application
2448 to use the modified definitions.)
2451 Accompany the work with a written offer, valid for at
2452 least three years, to give the same user the materials
2453 specified in Subsection 6a, above, for a charge no more
2454 than the cost of performing this distribution.
2457 If distribution of the work is made by offering access to copy
2458 from a designated place, offer equivalent access to copy the above
2459 specified materials from the same place.
2462 Verify that the user has already received a copy of these
2463 materials or that you have already sent this user a copy.
2466 For an executable, the required form of the ``work that uses the
2467 Library'' must include any data and utility programs needed for
2468 reproducing the executable from it. However, as a special exception,
2469 the source code distributed need not include anything that is normally
2470 distributed (in either source or binary form) with the major
2471 components (compiler, kernel, and so on) of the operating system on
2472 which the executable runs, unless that component itself accompanies
2475 It may happen that this requirement contradicts the license
2476 restrictions of other proprietary libraries that do not normally
2477 accompany the operating system. Such a contradiction means you cannot
2478 use both them and the Library together in an executable that you
2482 You may place library facilities that are a work based on the
2483 Library side-by-side in a single library together with other library
2484 facilities not covered by this License, and distribute such a combined
2485 library, provided that the separate distribution of the work based on
2486 the Library and of the other library facilities is otherwise
2487 permitted, and provided that you do these two things:
2491 Accompany the combined library with a copy of the same work
2492 based on the Library, uncombined with any other library
2493 facilities. This must be distributed under the terms of the
2497 Give prominent notice with the combined library of the fact
2498 that part of it is a work based on the Library, and explaining
2499 where to find the accompanying uncombined form of the same work.
2503 You may not copy, modify, sublicense, link with, or distribute
2504 the Library except as expressly provided under this License. Any
2505 attempt otherwise to copy, modify, sublicense, link with, or
2506 distribute the Library is void, and will automatically terminate your
2507 rights under this License. However, parties who have received copies,
2508 or rights, from you under this License will not have their licenses
2509 terminated so long as such parties remain in full compliance.
2512 You are not required to accept this License, since you have not
2513 signed it. However, nothing else grants you permission to modify or
2514 distribute the Library or its derivative works. These actions are
2515 prohibited by law if you do not accept this License. Therefore, by
2516 modifying or distributing the Library (or any work based on the
2517 Library), you indicate your acceptance of this License to do so, and
2518 all its terms and conditions for copying, distributing or modifying
2519 the Library or works based on it.
2522 Each time you redistribute the Library (or any work based on the
2523 Library), the recipient automatically receives a license from the
2524 original licensor to copy, distribute, link with or modify the Library
2525 subject to these terms and conditions. You may not impose any further
2526 restrictions on the recipients' exercise of the rights granted herein.
2527 You are not responsible for enforcing compliance by third parties to
2531 If, as a consequence of a court judgment or allegation of patent
2532 infringement or for any other reason (not limited to patent issues),
2533 conditions are imposed on you (whether by court order, agreement or
2534 otherwise) that contradict the conditions of this License, they do not
2535 excuse you from the conditions of this License. If you cannot
2536 distribute so as to satisfy simultaneously your obligations under this
2537 License and any other pertinent obligations, then as a consequence you
2538 may not distribute the Library at all. For example, if a patent
2539 license would not permit royalty-free redistribution of the Library by
2540 all those who receive copies directly or indirectly through you, then
2541 the only way you could satisfy both it and this License would be to
2542 refrain entirely from distribution of the Library.
2544 If any portion of this section is held invalid or unenforceable under any
2545 particular circumstance, the balance of the section is intended to apply,
2546 and the section as a whole is intended to apply in other circumstances.
2548 It is not the purpose of this section to induce you to infringe any
2549 patents or other property right claims or to contest validity of any
2550 such claims; this section has the sole purpose of protecting the
2551 integrity of the free software distribution system which is
2552 implemented by public license practices. Many people have made
2553 generous contributions to the wide range of software distributed
2554 through that system in reliance on consistent application of that
2555 system; it is up to the author/donor to decide if he or she is willing
2556 to distribute software through any other system and a licensee cannot
2559 This section is intended to make thoroughly clear what is believed to
2560 be a consequence of the rest of this License.
2563 If the distribution and/or use of the Library is restricted in
2564 certain countries either by patents or by copyrighted interfaces, the
2565 original copyright holder who places the Library under this License may add
2566 an explicit geographical distribution limitation excluding those countries,
2567 so that distribution is permitted only in or among countries not thus
2568 excluded. In such case, this License incorporates the limitation as if
2569 written in the body of this License.
2572 The Free Software Foundation may publish revised and/or new
2573 versions of the Library General Public License from time to time.
2574 Such new versions will be similar in spirit to the present version,
2575 but may differ in detail to address new problems or concerns.
2577 Each version is given a distinguishing version number. If the Library
2578 specifies a version number of this License which applies to it and
2579 ``any later version'', you have the option of following the terms and
2580 conditions either of that version or of any later version published by
2581 the Free Software Foundation. If the Library does not specify a
2582 license version number, you may choose any version ever published by
2583 the Free Software Foundation.
2586 If you wish to incorporate parts of the Library into other free
2587 programs whose distribution conditions are incompatible with these,
2588 write to the author to ask for permission. For software which is
2589 copyrighted by the Free Software Foundation, write to the Free
2590 Software Foundation; we sometimes make exceptions for this. Our
2591 decision will be guided by the two goals of preserving the free status
2592 of all derivatives of our free software and of promoting the sharing
2593 and reuse of software generally.
2596 @heading NO WARRANTY
2603 BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
2604 WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
2605 EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
2606 OTHER PARTIES PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY
2607 KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
2608 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
2609 PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
2610 LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
2611 THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
2614 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
2615 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
2616 AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
2617 FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
2618 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
2619 LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
2620 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
2621 FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
2622 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
2627 @heading END OF TERMS AND CONDITIONS
2630 @center END OF TERMS AND CONDITIONS
2634 @unnumberedsec How to Apply These Terms to Your New Libraries
2636 If you develop a new library, and you want it to be of the greatest
2637 possible use to the public, we recommend making it free software that
2638 everyone can redistribute and change. You can do so by permitting
2639 redistribution under these terms (or, alternatively, under the terms of the
2640 ordinary General Public License).
2642 To apply these terms, attach the following notices to the library. It is
2643 safest to attach them to the start of each source file to most effectively
2644 convey the exclusion of warranty; and each file should have at least the
2645 ``copyright'' line and a pointer to where the full notice is found.
2648 @var{one line to give the library's name and an idea of what it does.}
2649 Copyright (C) @var{year} @var{name of author}
2651 This library is free software; you can redistribute it and/or modify it
2652 under the terms of the GNU Library General Public License as published
2653 by the Free Software Foundation; either version 2 of the License, or (at
2654 your option) any later version.
2656 This library is distributed in the hope that it will be useful, but
2657 WITHOUT ANY WARRANTY; without even the implied warranty of
2658 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
2659 Library General Public License for more details.
2661 You should have received a copy of the GNU Library General Public
2662 License along with this library; if not, write to the Free Software
2663 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
2666 Also add information on how to contact you by electronic and paper mail.
2668 You should also get your employer (if you work as a programmer) or your
2669 school, if any, to sign a ``copyright disclaimer'' for the library, if
2670 necessary. Here is a sample; alter the names:
2673 Yoyodyne, Inc., hereby disclaims all copyright interest in the library
2674 `Frob' (a library for tweaking knobs) written by James Random Hacker.
2676 @var{signature of Ty Coon}, 1 April 1990
2677 Ty Coon, President of Vice
2680 That's all there is to it!
2683 @c Part 6: The End of the Document
2684 @c ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
2686 @c ***********************************************************************
2687 @c **** Concept Index ****************************************************
2688 @c ***********************************************************************
2690 @node Concept Index, , LGPL, Top
2691 @unnumbered Concept Index
2698 @c ***********************************************************************
2699 @c **** Contents *********************************************************
2700 @c ***********************************************************************