revert between 56095 -> 55830 in arch

[AROS.git] / workbench / devs / AHI / Docs / ahidev.texinfo

\input tmp-iso.sty
\input texinfo             @c -*-texinfo-*-
@c %***start of header
@setfilename ahidev.info
@settitle @sc{Ahi} Developers's Guide
@setchapternewpage odd
@iftex
@afourpaper
@end iftex
@c %***end of header

@c *** Variables ***

@c Set ahiver and docver to current release version
@include ahidev.ver


@c Part 2: Summary Description and Copyright
@c ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

@ifinfo
This file documents AHI release @value{ahiver}, a hardware independent
audio subsystem for Amiga. The version number of this document is
@value{docver}.

Copyright @copyright{} 1994-2005 Martin Blom.

Permission is granted to make and distribute verbatim copies of this manual
provided the copyright notice and this permission notice are preserved on
all copies.
     
@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission notice
identical to this one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``Distribution'', ``GPL'' and ``LGPL'' are included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Free Software Foundation.

@sc{This publication is provided by the author ``as is'' and any express or
implied warranties, including, but not limited to, the implied warranties
of merchantability and fitness for a particular purpose are disclaimed.  In
no event shall the author be liable for any direct, indirect, incidental,
special, exemplary, or consequential damages (including, but not limited
to, procurement of substitute goods or services; loss of use, data, or
profits; or business interruption) however caused and on any theory of
liability, whether in contract, strict liability, or tort (including
negligence or otherwise) arising in any way out of the use of this
publication, even if advised of the possibility of such damage.}

@example

$Id$
$Log: ahidev.texinfo,v $
Revision 5.3.2.3  2005/02/02 21:49:52  martin
* Updated all copyright years to 2005.

* Bumped all version numbers to 6.0.

* Docs/ahidev.texinfo (The Author): Updated the authors address (5
years later).

Revision 5.3.2.2  2004/11/02 13:18:53  martin
Updated copyright year and removed almost all CVS/RCS tags from the
source code.

Revision 5.3.2.1  2004/06/08 21:16:16  martin
Added 7.1 multichannel support.

Revision 5.3  2003/01/19 16:15:40  martin
Added descriptions of AHIA_AntiClickSamples and AHISF_NODELAY.

Revision 5.2  2003/01/19 14:24:45  martin
Added support for playing 32 bit samples.

Revision 5.1  2003/01/19 12:22:41  martin
Another year, another copyright update.
 ... which seems to have caused the translation files to change slightly.

Revision 5.0  2000/11/28 00:16:18  lcs
Bumped CVS revision to 5.0.

Revision 4.15  1999/09/19 14:05:03  lcs
Some polishing.

Revision 4.12  1999/09/19 13:10:18  lcs
Fixed some typos.
Changes license.

Revision 4.11  1999/03/28 22:32:46  lcs
AHI is now GPL/LGPL software.
Make target bindist work correctly when using a separate build directory.
Small first steps towards a WarpOS PPC version.

Revision 4.10  1999/01/10 19:27:46  lcs
The move to GNU make is done.

Revision 4.9  1999/01/10 16:07:56  lcs
Moved to GNU make (still moving...)

Revision 4.8  1998/01/18 19:50:42  lcs
I have no idea.

Revision 4.7  1997/10/21 01:33:40  lcs
The version number is now the AHI release version, not the documents version.

Revision 4.6  1997/08/21 01:11:30  lcs
Added description of the samle formats AHI_LoadSound() understands

Revision 4.5  1997/08/10 15:38:57  lcs
Added @@ahi macro!
Added note about LoadSound:ing the most important sounds first

Revision 4.4  1997/07/27 00:13:32  lcs
Fixed a mistypeing: was SetFreq() instead of AHI_SetFreq().

Revision 4.3  1997/07/15 00:50:40  lcs
This is the second bugfix release of AHI 4.

Revision 4.2  1997/05/11 12:38:39  lcs
Added note about unrolling short sounds.

Revision 4.1  1997/05/04 15:52:15  lcs
Initial revision.

@end example

@end ifinfo

@c Part 3: Titlepage and Copyright
@c ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

@titlepage
@title AHI
@subtitle Hardware independent audio for Amiga
@subtitle AHI Developer's Guide for AHI release @value{ahiver}
@subtitle Document version @value{docver}
@author Martin 'Leviticus' Blom

@page

@vskip 0pt plus 1filll

Copyright @copyright{} 1994-2005 Martin Blom. 

Permission is granted to make and distribute verbatim copies of this manual
provided the copyright notice and this permission notice are preserved on
all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``Distribution'', ``GPL'' and ``LGPL'' are included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Free Software Foundation.

@sc{This publication is provided by the author ``as is'' and any express or
implied warranties, including, but not limited to, the implied warranties
of merchantability and fitness for a particular purpose are disclaimed.  In
no event shall the author be liable for any direct, indirect, incidental,
special, exemplary, or consequential damages (including, but not limited
to, procurement of substitute goods or services; loss of use, data, or
profits; or business interruption) however caused and on any theory of
liability, whether in contract, strict liability, or tort (including
negligence or otherwise) arising in any way out of the use of this
publication, even if advised of the possibility of such damage.}

@end titlepage


@c Part 4: `Top' Node and Master Menu
@c ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

@node    Top, Overview, (dir), (dir)

@ifinfo

@majorheading @sc{Ahi} Developer's Guide

For @sc{Ahi} release @value{ahiver}. Document version @value{docver}.

Copyright @copyright{} 1994-2005 Martin Blom

The latest release of @sc{Ahi} can always be found at
@url{http://www.lysator.liu.se/~lcs/ahi.html}. 

@menu
* Overview::                    Brief introduction
* Distribution::                What you are allowed to do and not
* The Author::                  Who designed it?

* Definitions::                 Terms used in this document
* Function Interface::          The low-level API
* Device Interface::            The high-level API
* Data Types And Structures::   The structures explained

* GPL::                         The main license
* LGPL::                        The @code{ahi.device} license

* Concept Index::               Concept Index
* Data Type Index::             Data Type Index
* Function Index::              Function Index
* Variable Index::              Variable Index

@detailmenu
 --- The Detailed Node Listing ---

Function Interface

* Guidelines::                  
* Opening And Closing ahi.device For Low-level Access::  
* Obtaining The Hardware::      
* Declaring Sounds::            
* Making Noise::                

Device Interface

* Opening And Closing ahi.device For High-level Access::  
* Reading From The Device::     
* Writing To The Device::       

Data Types And Structures

* Data Types::                  
* Structures::                  

@end detailmenu
@end menu

@end ifinfo


@c Part 5:  The Body of the Document
@c ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯


@c ***********************************************************************
@c **** Overview *********************************************************
@c ***********************************************************************

@node Overview, Distribution, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Overview

@cindex Overview

This document was written in order to make it easier for developers to
understand and use @sc{Ahi} in their own productions, and write Software
That Works(TM).

@code{ahi.device} has two different API's; one library-like function
interface (low-level), and one ``normal'' device interface (high-level).
Each of them serves different purposes.  The low-level interface is
targeting music players, games and real-time applications. The high-level
interface is targeting applications that just want to have a sample played,
play audio streams or record samples as easily as possible.

As with everything else, it is important that you chose the right tool for
the job---you'll only get frustrated otherwise.

Not everything about @sc{Ahi} is documented here; for more information, see
@cite{@sc{Ahi} User's Guide} and the autodocs.


@c ***********************************************************************
@c **** Distribution *****************************************************
@c ***********************************************************************

@node  Distribution, The Author, Overview, Top
@comment  node-name,  next,  previous,  up
@chapter Distribution

@cindex Distribution
@cindex Disclaimer
@cindex License
@cindex Legal nonsense
@cindex Software license
@cindex Copyright

Copyright @copyright{} 1994-2005 Martin Blom

@sc{Ahi} is available under a dual license. The device itself is under
the ``GNU Library General Public License'' (@pxref{LGPL}), while the
utility programs and the @code{AUDIO:} device is covered by the ``GNU General
Public License'' (@pxref{GPL}).

If you use this software in a commercial or shareware product, please
consider giving the author (@pxref{The Author})---and preferably each one
of the contributors too (see @cite{@sc{Ahi} User's Guide})---an original or
registered copy or sample of your work.  Should you want to distribute the
@sc{Ahi} software with your own product, there is really nothing to
consider, right?


@c ***********************************************************************
@c **** The Author *******************************************************
@c ***********************************************************************

@node  The Author, Definitions, Distribution, Top
@comment  node-name,  next,  previous,  up
@chapter The Author

@cindex The Author
@cindex Author of @sc{Ahi}

The author can be reached at the following addresses:

@table @asis

@item Electronic mail
@email{martin@@blom.org}

@item Standard mail
  Martin Blom
@*Luftvärnsgatan 42
@*SE-587 34 Linköping
@*Sweden

@item World-Wide Web
@url{http://martin.blom.org}

@end table


@c ***********************************************************************
@c **** Definitions  *****************************************************
@c ***********************************************************************

@node Definitions, Function Interface, The Author, Top
@comment  node-name,  next,  previous,  up
@chapter Definitions

@cindex Definitions

Following are some general definitions of terms that are used in this
document.

@table @dfn

@cindex Sample

@item Sample
A sample is one binary number, representing the amplitude at a fixed point
in time.  A sample is often stored as an 8 bit signed integer, a 16 bit
signed integer, a 32 bit floating point number etc.  @sc{Ahi} only
supports integers.

@cindex Sample frame

@item Sample frame
In mono environments, a sample frame is the same as a sample.  In stereo
environments, a sample frame is a tuple of two samples.  The first member
is for the left channel, the second for the right.

@cindex Sound

@item Sound
Many sample frames stored in sequence as an array can be called a sound.  A
sound is, however, not limited to being formed by samples, it can also be
parameters to an analog synth or a MIDI instrument, or be white noise.
@sc{Ahi} only supports sounds formed by samples.

@end table


@c ***********************************************************************
@c ***********************************************************************
@c **** Function Interface ***********************************************
@c ***********************************************************************
@c ***********************************************************************

@node Function Interface, Device Interface, Definitions, Top
@comment  node-name,  next,  previous,  up
@chapter Function Interface

@cindex Function Interface

 The device has, in addition to the usual I/O request protocol, a set of
functions that allows the programmer to gain full control (at least as much
as possible with device independence) over the audio hardware.  The
advantages are low overhead and much more advanced control over the playing
sounds.  The disadvantages are greater complexity and only one user per
sound card.

@cindex Music, games
@cindex Sound effects, games
@cindex Games, music
@cindex Games, sound effects
@cindex Realtime effects
@cindex Recording, high quality

 If you want to play music or sound effects for a game, record in high
quality or want to do realtime effects, this is the API to use.



@menu
* Guidelines::                  
* Opening And Closing ahi.device For Low-level Access::  
* Obtaining The Hardware::      
* Declaring Sounds::            
* Making Noise::                
@end menu


@c ***********************************************************************
@c **** Guidelines *******************************************************
@c ***********************************************************************

@node Guidelines, Opening And Closing ahi.device For Low-level Access, Function Interface, Function Interface
@comment  node-name,  next,  previous,  up
@section Guidelines

@cindex Guidelines
@cindex Programming guidelines


@subsection Follow The Rules

 It's really simple.  If I tell you to check return values, check sample
types when recording, not to trash d2-d7/a2-a6 in hooks, or not to call
@code{AHI_ControlAudio()} with the @code{AHIC_Play} tag from interrupts or
hooks, you do as you are told.


@subsection The Library Base

@cindex Library base
@tindex AHIBase

 The @code{AHIBase} structure is private, so are the sub libraries' library
base structures.  Don't try to be clever.


@subsection The Audio Database

@cindex The Audio Database

@findex AHI_NextAudioID()
@findex AHI_GetAudioAttrsA()
@findex AHI_BestAudioIDA()

 The implementation of the database is private, and may change any time.
@code{ahi.device} provides functions access the information in the database
(@code{AHI_NextAudioID()}, @code{AHI_GetAudioAttrsA()} and
@code{AHI_BestAudioIDA()}).


@subsection User Hooks

@cindex Hooks

 All user hooks must follow normal register conventions, which means that
d2-d7 and a2-a6 must be preserved.  They may be called from an interrupt,
but you cannot count on that; it can be your own process or another
process.  Don't assume the system is in single-thread mode.  Never spend
much time in a hook, get the work done as quick as possible and then
return.


@subsection Function Calls From Other Tasks, Interrupts Or User Hooks

 The @code{AHIAudioCtrl} structure may not be shared with other
tasks/threads.  The task that called @code{AHI_AllocAudioA()} must do all
other calls too (except those callable from interrupts).

 Only calls specifically said to be callable from interrupts may be called
from user hooks or interrupts.  Note that @code{AHI_ControlAudioA()} has
some tags that must not be present when called from an interrupt.


@subsection Multitasking

@cindex Multitasking

 Most audio drivers need multitasking to be turned on to function properly.
Don't turn it off while using the device.



@c ***********************************************************************
@c **** Opening And Closing ahi.device For Low-level Access **************
@c ***********************************************************************

@node Opening And Closing ahi.device For Low-level Access, Obtaining The Hardware, Guidelines, Function Interface
@comment  node-name,  next,  previous,  up
@section Opening And Closing @code{ahi.device} For Low-level Access


 Not too hard.  Just open @code{ahi.device} unit @code{AHI_NO_UNIT} and
initialize @code{AHIBase}.  After that you can access all the functions of
the device just as if you had opened a standard shared library.


@subsection @code{Assembler}

 For the assembler programmer there are two handy macros: @code{OPENAHI}
and @code{CLOSEAHI}.  Here is a small example how to use them:

@example
        OPENAHI 4                  ;Open at least version 4.
        lea     _AHIBase(pc),a0
        move.l  d0,(a0)
        beq     error

; AHI's functions can now be called as normal library functions:
        move.l  _AHIBase(pc),a6
        moveq   #AHI_INVALID_ID,d0
        jsr     _LVOAHI_NextAudioID(a6)

error:
        CLOSEAHI
        rts
@end example


 Note that you @strong{have} to execute the @code{CLOSEAHI} macro even if
@code{OPENAHI} failed!


@subsection @code{C}

 For the C programmer, here is how it should be done:

@noindent
@example
struct Library    *AHIBase;
struct MsgPort    *AHImp=NULL;
struct AHIRequest *AHIio=NULL;
BYTE               AHIDevice=-1;

if(AHImp = CreateMsgPort())
@{
  if(AHIio = (struct AHIRequest *) CreateIORequest(
      AHImp, sizeof(struct AHIRequest)))
  @{
    AHIio->ahir_Version = 4;  /* Open at least version 4. */
    if(!(AHIDevice = OpenDevice(AHINAME, AHI_NO_UNIT,
        (struct IORequest *) AHIio, NULL)))
    @{
      AHIBase = (struct Library *) AHIio->ahir_Std.io_Device;

// AHI's functions can now be called as normal library functions:
      AHI_NextAudioID(AHI_INVALID_ID);

      CloseDevice((struct IORequest *) AHIio);
      AHIDevice = -1;
    @}
    DeleteIORequest((struct IORequest *) AHIio);
    AHIio = NULL;
  @}
  DeleteMsgPort(AHImp);
  AHImp = NULL;
@}
@end example



@c ***********************************************************************
@c **** Obtaining The Hardware *******************************************
@c ***********************************************************************

@node Obtaining The Hardware, Declaring Sounds, Opening And Closing ahi.device For Low-level Access, Function Interface
@comment  node-name,  next,  previous,  up
@section Obtaining The Hardware

 If you wish to call any other function than

@itemize @bullet

@item
@code{AHI_AllocAudioRequestA()}

@item
@code{AHI_AudioRequestA()}

@item
@code{AHI_BestAudioIDA()}

@item
@code{AHI_FreeAudioRequest()}

@item
@code{AHI_GetAudioAttrsA()}

@item
@code{AHI_NextAudioID()}

@item
@code{AHI_SampleFrameSize()}

@end itemize

@findex AHI_AllocAudioA()
@tindex AHIAudioCtrl
@vindex ahiac_UserData

@dots{}you have to allocate the actual sound hardware.  This is done with
@code{AHI_AllocAudioA()}.  @code{AHI_AllocAudioA()} returns an
@code{AHIAudioCtrl} structure, or @code{NULL} if the hardware could not be
allocated.  The @code{AHIAudioCtrl} structure has only one public field,
@code{ahiac_UserData}.  This is unused by @sc{Ahi} and you may store
anything you like here.

 If @code{AHI_AllocAudioA()} fails it is important that you handle the
situation gracefully.

@findex AHI_FreeAudio()

 When you are finished playing or recording, call @code{AHI_FreeAudio()} to
deallocate the hardware and other resources allocated by
@code{AHI_AllocAudioA()}.  @code{AHI_FreeAudio()} also deallocates all
loaded sounds (@pxref{Declaring Sounds}).


@subsection @code{AHI_AllocAudioA()} Tags

@code{AHI_AllocAudioA()} takes several tags as input.

@vtable @code

@vindex AHI_DEFAULT_ID

@item AHIA_AudioID
This is the audio mode to be used.  You must not use any hardcoded values
other than @code{AHI_DEFAULT_ID}, which is the user's default fallback ID.
In most cases you should ask the user for an ID code (with
@code{AHI_AudioRequestA()}) and then store the value in your settings file.

@vindex AHI_DEFAULT_FREQ

@item AHIA_MixFreq
This is the mixing frequency to be used.  The actual frequency will be
rounded to the nearest frequency supported by the sound hardware.  To find
the actual frequency, use @code{AHI_GetAudioAttrsA()}.  If omitted or
@code{AHI_DEFAULT_FREQ}, the user's preferred fallback frequency will be
used.  In most cases you should ask the user for a frequency (with
@code{AHI_AudioRequestA()}) and then store the value in your settings file.

@item AHIA_Channels
All sounds are played on a @dfn{channel}, and this tag selects how many you
wish to use.  In general it takes more CPU power the more channels you use
and the volume gets lower and lower.

@item AHIA_Sounds
You must tell @sc{Ahi} how many different sounds you are going to play.
@xref{Declaring Sounds} for more information.

@tindex AHISoundMessage
@vindex ahism_Channel

@item AHIA_SoundFunc
With this tag you tell @sc{Ahi} to call a hook when a sound has been
started.  It works just like Paula's audio interrupts.  The hook receives an
@code{AHISoundMessage} structure as message.
@code{AHISoundMessage->ahism_Channel} indicates which channel the sound
that caused the hook to be called is played on.

@item AHIA_PlayerFunc
If you are going to play a musical score, you should use this ``interrupt''
source instead of VBLANK or CIA timers in order to get the best result with
all audio drivers.  If you cannot use this, you must not use any
``non-realtime'' modes (see @code{AHI_GetAudioAttrsA()} in the autodocs,
the @code{AHIDB_Realtime} tag).

@item AHIA_PlayerFreq
If non-zero, it enables timing and specifies how many times per second
@code{PlayerFunc} will be called.  This must be specified if
@code{AHIA_PlayerFunc} is!  It is suggested that you keep the frequency
below 100-200 Hz.  Since the frequency is a fixpoint number
@code{AHIA_PlayerFreq} should be less than 13107200 (that's 200 Hz).

@item AHIA_MinPlayerFreq
The minimum frequency (@code{AHIA_PlayerFreq}) you will use.  You should
always supply this if you are using the device's interrupt feature!

@item AHIA_MaxPlayerFreq
The maximum frequency (@code{AHIA_PlayerFreq}) you will use.  You should
always supply this if you are using the device's interrupt feature!

@item AHIA_RecordFunc
This hook will be called regularly when sampling is turned on (see
@code{AHI_ControlAudioA()}).  It is important that you always check the
format of the sampled data, and ignore it if you can't parse it.  Since
this hook may be called from an interrupt, it is not legal to directly
@code{Write()} the buffer to disk.  To record directly to harddisk you
have to copy the samples to another buffer and signal a process to save it.
To find out the required size of the buffer, see
@code{AHI_GetAudioAttrsA()} in the autodocs, the
@code{AHIDB_MaxRecordSamples} tag.

@vindex ahiac_UserData

@item AHIA_UserData
Can be used to initialize the @code{ahiac_UserData} field.  You do not have
to use this tag to change @code{ahiac_UserData}, you may write to it
directly.

@item AHIA_AntiClickSamples
New for version 6, this tag specifies how many sample frames a sound
may be delayed when started in order to reduce clicking. In practice,
the currently playing sound will continue until a zero-crossing is
found or @code{AHIA_AntiClickSamples} samples have been
processed. After that, the new sound will be started.

The default for this tag can be set by the user in the preferences
program. Set it to 0 to disable this feature.

@end vtable

@c ***********************************************************************
@c **** Declaring Sounds *************************************************
@c ***********************************************************************

@node Declaring Sounds, Making Noise, Obtaining The Hardware, Function Interface
@comment  node-name,  next,  previous,  up
@section Declaring Sounds

@cindex Loading Sounds
@cindex Unloading Sounds

@findex AHI_LoadSound()

Before you can play a sample array, you must @code{AHI_LoadSound()} it.
Why?  Because if @sc{Ahi} knows what kind of sounds that will be played
later, tables and stuff can be set up in advance.  Some drivers may even
upload the samples to the sound cards local RAM and play all samples from
there, drastically reducing CPU and bus load.

You should @code{AHI_LoadSound()} the most important sounds first, since
the sound cards RAM may not be large enough to hold all your sounds.

@code{AHI_LoadSound()} also associates each sound or sample array with a
number, which is later used to refer to that particular sound.

 There are 2 types of sounds, namely @code{AHIST_SAMPLE} and
@code{AHIST_DYNAMICSAMPLE}.

@c and @code{AHIST_INPUT}.

@vtable @code

@item AHIST_SAMPLE
This is used for static samples.  Most sounds that will be played are of
this type.  Once the samples have been ``loaded'', you may not alter the
memory where the samples are located.  You may, however, read from it.

@item AHIST_DYNAMICSAMPLE
If you wish to play samples that you calculate in realtime, or load in
portions from disk, you must use this type.  These samples will never be
uploaded to a sound cards local RAM, but always played from the normal
memory.  There is a catch, however.  Because of the fact that the sound is
mixed in chunks, you must have a certain number of samples in memory before
you start a sound of this type.  To calculate the size of the buffer (in
samples), use the following formula:

@example
@math{size = samples * Fs / Fm}
@end example

where samples is the value returned from @code{AHI_GetAudioAttrsA()} when
called with the @code{AHIDB_MaxPlaySamples} tag, Fs is the highest
frequency the sound will be played at and Fm is the actual mixing frequency
(@code{AHI_ControlAudioA()/AHIC_MixFreq_Query}).


@c @item AHIST_INPUT
@c This sound type is used to use @sc{Ahi}'s DSP-effects in real-time.  [It
@c does not work yet. FIXIT]

@end vtable

The samples can be in one of seven different formats, named @code{AHIST_M8S},
@code{AHIST_S8S}, @code{AHIST_M16S}, @code{AHIST_S16S}, @code{AHIST_M32S},
@code{AHIST_S32S} and @code{AHIST_L7_1}

@vtable @code

@item AHIST_M8S
This is an 8 bit mono sound. Each sample frame is just one signed byte.

@item AHIST_S8S
This is an 8 bit stereo sound. Each sample frame is one signed byte representing
the left channel, followed by another one for the right channel.

@item AHIST_M16S
This is a 16 bit mono sound.  Each sample frame is just one signed 16 bit
word, in big endian/network order format (most significant byte first).

@item AHIST_S16S
This is a 16 bit stereo sound.  Each sample frame is one signed 16 bit
word, in big endian/network order format (most significant byte first)
representing the left channel, followed by another one for the right
channel.

@item AHIST_M32S
This is a 32 bit mono sound.  Each sample frame is just one signed 32
bit word, in big endian/network order format (most significant byte
first).  Note that only the 24 most significant bits are guaranteed to
be processed correctly! Support for this sample format was added in
V6.

@item AHIST_S32S
This is a 32 bit stereo sound.  Each sample frame is one signed 32 bit
word, in big endian/network order format (most significant byte first)
representing the left channel, followed by another one for the right
channel. Note that only the 24 most significant bits are guaranteed to
be processed correctly! Support for this sample format was added in
V6.

@item AHIST_L7_1
This is a 32 bit 7.1 sound.  @strong{It will currently only work with
7.1 audio modes!} Each sample frame is one signed 32 bit word, in big
endian/network order format (most significant byte first) representing
the left front channel, followed by six other words for the right
front, left back, right back, left surround, right surround, front
center and the LFE channel. Note that only the 24 most significant
bits are guaranteed to be processed correctly! ``Support'' for this
sample format was added in V6.

@end vtable

@findex AHI_UnloadSound()

 If you know that you won't use a sound anymore, call
@code{AHI_UnloadSound()}.  @code{AHI_FreeAudio()} will also do that for you
for any sounds left when called.

 There is no need to place a sample array in @dfn{Chip memory}, but it
@strong{must not} be swapped out!  Allocate your sample memory with the
@code{MEMF_PUBLIC} flag set.  If you wish to have your samples in virtual
memory, you have to write a double-buffer routine that copies a chunk of
memory to a @code{MEMF_PUBLIC} buffer.  The @dfn{SoundFunc} should signal a
task to do the transfer, since it may run in supervisor mode (see
@code{AHI_AllocAudioA()}).


@c ***********************************************************************
@c **** Making Noise *****************************************************
@c ***********************************************************************

@node Making Noise,  , Declaring Sounds, Function Interface
@comment  node-name,  next,  previous,  up
@section Making Noise

@findex AHI_ControlAudioA()
@vindex AHIC_Play

After you have allocated the sound hardware and declared all your sounds,
you're ready to start playback.  This is done with a call to
@code{AHI_ControlAudioA()}, with the @code{AHIC_Play} tag set to
@code{TRUE}.  When this function returns the @dfn{PlayerFunc} (see
@code{AHI_AllocAudioA()}) is active, and the audio driver is feeding
silence to the sound hardware.

@subsection Playing A Sound

@findex AHI_SetSound()
@findex AHI_SetFreq()
@findex AHI_SetVol()

All you have to do now is to set the desired sound, it's frequency and
volume.  This is done with @code{AHI_SetSound()}, @code{AHI_SetFreq()} and
@code{AHI_SetVol()}.  Make sure the @code{AHISF_IMM} flag is set for all
these function's @var{flag} argument.  And don't try to modify a channel
that is out of range!  If you have allocated 4 channels you may only modify
channels 0-3.

The sound will not start until both @code{AHI_SetSound()} and
@code{AHI_SetFreq()} have been called.  The sound will play even if
@code{AHI_SetVol()} was not called, but it will play completely silent.  If
you wish to temporary stop a sound, set its frequency to 0.  When you
change the frequency again, the sound will continue where it was.

@vindex AHISF_NODELAY

The actual beginning of sound might be delayed slightly, depending on
the value of the @code{AHIA_AntiClickSamples} tag passed to
@code{AHI_AllocAudioA()}. Should you wish to override this, set the
@code{AHISF_NODELAY} in addition to @code{AHISF_IMM}.


@findex AHI_PlayA()

When the sound has been started it will play to the end and then repeat.
In order to play a one-shot sound you have use the @code{AHI_PlayA()}
function, or install a sound interrupt using the @code{AHIA_SoundFunc} tag
with @code{AHI_AllocAudioA()}.  For more information about using sound
interrupts, see below.

A little note regarding @code{AHI_SetSound()}:  @var{Offset} is the first
sample frame that will be played, both when playing backwards and forwards.
This means that if you call @code{AHI_SetSound()} with @var{offset} 0 and
@var{length} 4, sample fram 0, 1, 2 and 3 will be played.  If you call
@code{AHI_SetSound()} with @var{offset} 3 and @var{length} @minus{}4,
sample frame 3, 2, 1 and 0 will be played.

Also note that playing very short sounds will be very CPU intensive, since
there are many tasks that must be done each time a sound has reached its
end (like starting the next one, calling the @dfn{SoundFunc}, etc.).
Therefore, it is recommended that you ``unroll'' short sounds a couple of
times before you play them.  How many times you should unroll?  Well, it
depends on the situation, of course, but try making the sound a thousand
samples long if you can. Naturally, if you need your @dfn{SoundFunc} to
be called, you cannot unroll.

@subsection Playing One-shot Sounds And Advanced Loops

@vindex AHISF_IMM

 In version 4, some changes have been made since earlier releases.
One-shot sounds and sounds with only one loop segment can now be played
without using sample interrupts.  This is possible because one of the
restrictions regarding the @code{AHISF_IMM} flag has been removed.

 The @code{AHISF_IMM} flag determines if @code{AHI_SetSound()},
@code{AHI_SetFreq()} and @code{AHI_SetVol()} should take effect immediately
or when the current sound has reached its end.  The rules for this flags
are:

@itemize @bullet

@item
If used inside a sample interrupt (@dfn{SoundFunc}):  Must be cleared.

@item
If used inside a player interrupt (@dfn{PlayerFunc}):  May be set or
cleared.

@item
If used elsewhere:  Must be set.

@end itemize

 What does this mean?  It means that if all you want to do is to play a
one-shot sound from inside a @dfn{PlayerFunc}, you can do that by first
calling @code{AHI_SetSound()}, @code{AHI_SetFreq()} and @code{AHI_SetVol()}
with @code{AHISF_IMM} set, and then use @code{AHI_SetSound(ch, AHI_NOSOUND,
0, 0, actrl, 0L)} to stop the sound when it has reached the end.  You can
also set one loop segment this way.

 @code{AHI_PlayA()} was added in @sc{Ahi} version 4, and combines
@code{AHI_SetSound()}, @code{AHI_SetFreq()} and @code{AHI_SetVol()} into
one tag-based function.  It also allows you to set one loop and play
one-shot sounds.

 To play a sound with more than one loop segment or ping-pong looping, a
sample interrupt needs to be used.  @sc{Ahi}'s @dfn{SoundFunc} works like Paula's
interrupts and is very easy to use.

 The @dfn{SoundFunc} hook will be called with an @code{AHIAudioCtrl}
structure as object and an @code{AHISoundMessage} structure as message.
@code{ahism_Channel} indicates which channel caused the hook to be called.

 An example @dfn{SoundFunc} which handles the repeat part of an instrument
can look like this (SAS/C code):

@example
__asm __saveds ULONG SoundFunc(register __a0 struct Hook *hook,
    register __a2 struct AHIAudioCtrl *actrl,
    register __a1 struct AHISoundMessage *chan)
@{
  if(ChannelDatas[chan->ahism_Channel].Length)
    AHI_SetSound(chan->ahism_Channel, 0,
        (ULONG) ChannelDatas[chan->ahism_Channel].Address,
        ChannelDatas[chan->ahism_Channel].Length,
        actrl, NULL);
  else
    AHI_SetSound(chan->ahism_Channel, AHI_NOSOUND,
        NULL, NULL, actrl, NULL);
  return NULL;
@}
@end example


 This example is from an old version of the @sc{Ahi} NotePlayer for
@dfn{DeliTracker 2}.  @code{ChannelDatas} is an array where the start and
length of the repeat part is stored.  Here, a repeat length of zero
indicates a one-shot sound.  Note that this particular example only uses
one sound (0).  For applications using multiple sounds, the sound number
would have to be stored in the array as well.

 Once again, note that the @code{AHISF_IMM} flag should @strong{never} be
set in a @dfn{SoundFunc} hook!


@subsection Tricks With The Volume

@cindex Surround sound

 Starting with V4, @code{AHI_SetVol()} can take both negative volume and
pan parameters.  If you set the volume to a negative value, the sample
will, if the audio mode supports it, invert each sample before playing.  If
pan is negative, the sample will be encoded to go to the surround speakers.



@c ***********************************************************************
@c ***********************************************************************
@c **** Device Interface *************************************************
@c ***********************************************************************
@c ***********************************************************************

@node Device Interface, Data Types And Structures, Function Interface, Top
@comment  node-name,  next,  previous,  up
@chapter Device Interface

@cindex Music, streams from disk
@cindex Playing audio streams
@cindex Audio streams, playing
@cindex Sound effects, system
@cindex Recording, quick and easy

 The I/O request protocol makes it very easy to play audio streams, sounds
from disk and non time-critical sound effects in a multitasking friendly
way.  Recoding is just as easy, on behalf of quality.  Several programs can
play sounds at the same time, and even record at the same time if your
hardware is full duplex.

 If you want to write a sample player, play (warning?) sounds in your
applications, play an audio stream from a CD via the SCSI/IDE bus, write a
voice command utility etc., this is the API to use.

 Note that while all the low-level functions (@pxref{Function Interface})
count lengths and offsets in sample frames, the device interface---like all
Amiga devices---uses bytes.


@c ***********************************************************************
@c **** Opening And Closing ahi.device For High-level Access *************
@c ***********************************************************************

@menu
* Opening And Closing ahi.device For High-level Access::  
* Reading From The Device::     
* Writing To The Device::       
@end menu

@node Opening And Closing ahi.device For High-level Access, Reading From The Device, Device Interface, Device Interface
@comment  node-name,  next,  previous,  up
@section Opening And Closing @code{ahi.device} For High-level Access

 Four primary steps are required to open ahi.device:

@itemize @bullet

@item
Create a message port using @code{CreateMsgPort()}.  Reply messages from
the device must be directed to a message port.

@tindex AHIRequest

@item
Create an extended I/O request structure of type @code{AHIRequest} using
@code{CreateIORequest()}.  @code{CreateIORequest()} will initialize the I/O
request to point to your reply port.

@item
Specify which version of the device you need.  The lowest supported version
is 4.  Version 1 and 3 are obsolete, and version 2 only has the low-level
API.

@vindex AHI_DEFAULT_UNIT

@item
Open @code{ahi.device} unit @code{AHI_DEFAULT_UNIT} or any other unit the
user has specified with, for example, a @var{UNIT} tooltype.  Call
@code{OpenDevice()}, passing the I/O request.

@end itemize

 Each @code{OpenDevice()} must eventually be matched by a call to
@code{CloseDevice()}.  When the last close is performed, the device will
deallocate all resources.

 All I/O requests must be completed before @code{CloseDevice()}.  Abort any
pending requests with @code{AbortIO()}.

 Example:

@example
struct MsgPort    *AHImp      = NULL;
struct AHIRequest *AHIio      = NULL;
BYTE               AHIDevice  = -1;
UBYTE              unit       = AHI_DEFAULT_UNIT;

/* Check if user wants another unit here... */

if(AHImp = CreateMsgPort())
@{
  if(AHIio = (struct AHIRequest *)
      CreateIORequest(AHImp, sizeof(struct AHIRequest)))
  @{
    AHIio->ahir_Version = 4;
    if(!(AHIDevice = OpenDevice(AHINAME, unit, 
        (struct IORequest *) AHIio, NULL)))
    @{


      /* Send commands to the device here... */


      if(! CheckIO((struct IORequest *) AHIio))
      @{
        AbortIO((struct IORequest *) AHIio);
      @}

      WaitIO((struct IORequest *) AHIio);

      CloseDevice((struct IORequest *) AHIio);
      AHIDevice = -1;
    @}
    DeleteIORequest((struct IORequest *) AHIio);
    AHIio = NULL;
  @}
  DeleteMsgPort(AHImp);
  AHImp = NULL;
@}
@end example



@c ***********************************************************************
@c **** Reading From The Device ******************************************
@c ***********************************************************************

@node Reading From The Device, Writing To The Device, Opening And Closing ahi.device For High-level Access, Device Interface
@comment  node-name,  next,  previous,  up
@section Reading From The Device

@cindex Reading
@cindex Recording

@vindex CMD_READ
@vindex io_Command
@vindex io_Length
@vindex io_Data
@vindex ahir_Type
@vindex ahir_Frequency
@vindex io_Length
@vindex io_Offset

 You read from @code{ahi.device} by passing an @code{AHIRequest} to the
device with @code{CMD_READ} set in @code{io_Command}, the number of bytes
to be read set in @code{io_Length}, the address of the read buffer set in
@code{io_Data}, the desired sample format set in @code{ahir_Type} and the
desired sample frequency set in @code{ahir_Frequency}.  The first read
command in a sequence should also have @code{io_Offset} set to 0.
@code{io_Length} must be an even multiple of the sample frame size.

@subsection Double Buffering

@cindex Double Buffering, reading

 To do double buffering, just fill the first buffer with @code{DoIO()} and
@code{io_Offset} set to 0, then start filling the second buffer with
@code{SendIO()} using the same I/O request (but don't clear
@code{io_Offset}!).  After you have processed the first buffer, wait until
the I/O request is finished and start over with @code{SendIO()} on the
first buffer.

@subsection Distortion

@cindex Distortion, recording

 The samples will automatically be converted to the sample format set in
@code{ahir_Type} and to the sample frequency set in @code{ahir_Frequency}.
Because it is quite unlikely that you ask for the same sample frequency the
user has chosen in the preference program, chances that the quality is
lower than expected are pretty high.  The worst problem is probably the
anti-aliasing filter before the A/D converter.  If the user has selected a
higher sampling/mixing frequency than you request, the signal will be
distorted according to the Nyquist sampling theorem.  If, on the other
hand, the user has selected a lower sampling/mixing frequency than you
request, the signal will not be distorted but rather bandlimited more than
necessary.


@c ***********************************************************************
@c **** Writing To The Device ********************************************
@c ***********************************************************************

@node Writing To The Device,  , Reading From The Device, Device Interface
@comment  node-name,  next,  previous,  up
@section Writing To The Device

@cindex Writing
@cindex Playing

@vindex CMD_WRITE
@vindex io_Command
@vindex ln_Pri
@vindex io_Length
@vindex io_Data
@vindex ahir_Type
@vindex ahir_Frequency
@vindex ahir_Volume
@vindex ahir_Position
@vindex ahir_Link
@vindex io_Length


 You write to the device by passing an @code{AHIRequest} to the device with
@code{CMD_WRITE} set in @code{io_Command}, the precedence in
@code{io_Message.mn_Node.ln_Pri}, the number of bytes to be written in
@code{io_Length}, the address of the write buffer set in @code{io_Data},
the sample format set in @code{ahir_Type}, the desired sample frequency set
in @code{ahir_Frequency}, the desired volume set in @code{ahir_Volume} and
the desired stereo position set in @code{ahir_Position}.  Unless you are
doing double buffering, @code{ahir_Link} should be set to @code{NULL}.
@code{io_Length} must be an even multiple of the sample frame size.

@subsection Double Buffering

@cindex Double Buffering, writing

 To do double buffering, you need two I/O requests.  Create the second one
by making a copy of the request you used in @code{OpenDevice()}.  Start the
first with @code{SendIO()}.  Set @code{ahir_Link} in the second request to
the address of the first request, and @code{SendIO()} it.  Wait on the
first, fill the first buffer again and repeat, this time with
@code{ahir_Link} of the first buffer set to the address of the second I/O
request.

@subsection Distortion

@cindex Distortion, playing

 The problems with aliasing are present but not as obvious as with reading.
Just make sure your source data is bandlimited correctly, and do not play
samples at a lower frequency than they were recorded.

@subsection Playing multiple sounds at the same time

 If you want to play several sounds at the same time, just make a new copy
of the I/O request you used in @code{OpenDevice()}, and @code{CMD_WRITE}
it.  The user has set the number of channels available in the preference
tool, and if too many requests are sent to the device the one with lowest
precedence will be muted.  When a request is finished, the muted request
with the highest precedence will be played.  Note that all muted requests
continue to play silently, so the programmer will not have to worry if
there are enough channels or not.

@subsection Suggested precedences

@cindex Precedences

 The precedences to use depend on what kind of sound you are playing.  The
recommended precedences are the same as for @code{audio.device}, listed in
@cite{AMIGA ROM Kernel Reference manual -- Devices}.  Reprinted without
permission.  So sue me.

@example
 Precedences  | Type of sound
 -------------+----------------------------------------------------------
    127       |  Unstoppable.  Sounds first allocated at lower
              | precedencies, then set to this highest level.
    90 - 100  |  Emergencies.  Alert, urgent situation that requires
              | immediate action.
    80 - 90   |  Annunciators.  Attention, bell (CTRL-G).
    75        |  Speech.  Synthesized or recorded speech
              | (narrator.device).
    50 - 70   |  Sonic cues.  Sounds that provide information that is not
              | provided by graphics.  Only the beginning of of each sound
              | should be at this level; the rest should ne set to sound
              | effects level.
   -50 - 50   |  Music program.  Musical notes in a music-oriented program.
              | The higher levels should be used for the attack portions
              | of each note.
   -70 - -50  |  Sound effects.  Sounds used in conjunction with graphics.
              | More important sounds should use higher levels.
   -100 - -80 |  Background.  Theme music and restartable background sounds.
   -128       |  Silence.  Lowest level (freeing the channel completely is
              | preferred).
@end example

@c @multitable @columnfractions .15 .75
@c 
@c @item Precedences @tab Type of sound
@c 
@c @item 127
@c @tab Unstoppable.  Sounds first allocated at lower precendencies, then set
@c to this highest level.
@c 
@c @item 90 - 100
@c @tab Emergencies.  Alert, urgent situation that requires immediate action.
@c 
@c @item 80 - 90
@c @tab Annunciators.  Attention, bell (CTRL-G).
@c 
@c @item 75
@c @tab Speech.  Synthesized or recorded speech (narrator.device).
@c 
@c @item 50 - 70
@c @tab Sonic cues.  Sounds that provide information that is not
@c provided by graphics.  Only the beginning of of each sound
@c should be at this level; the rest should ne set to sound
@c effects level.
@c 
@c @item @minus{}50 - 50
@c @tab Music program.  Musical notes in a music-oriented program.  The higher
@c levels should be used for the attack portions of each note.
@c 
@c @item @minus{}70 - @minus{}50
@c @tab  Sound  effects.   Sounds  used  in  conjunction  with graphics.  More
@c important sounds should use higher levels.
@c 
@c @item @minus{}100 - @minus{}80
@c @tab Background.  Theme music and restartable background sounds.
@c 
@c @item @minus{}128
@c @tab Silence.  Lowest level (freeing the channel completely is preferred).
@c 
@c @end multitable

 Right.  As you can see, some things do not apply to @code{ahi.device}.
First, there is no way to change the precedence of a playing sound, so the
precedences should be set from the beginning.  Second, it is not
recommended to use the device interface to play music.  However, playing an
audio stream from CD or disk comes very close.  Third, there are no channels
to free in @sc{Ahi} since they are dynamically allocated by the device.


@c ***********************************************************************
@c ***********************************************************************
@c **** Data Types And Structures ****************************************
@c ***********************************************************************
@c ***********************************************************************

@node Data Types And Structures, GPL, Device Interface, Top
@comment  node-name,  next,  previous,  up
@chapter Data Types And Structures

@cindex Data Types And Structures

 In this chapter some of the data types and structures used will be
explained.  For more information, please consult the autodocs and the
include files.

@menu
* Data Types::                  
* Structures::                  
@end menu


@c ***********************************************************************
@c **** Data Types *******************************************************
@c ***********************************************************************

@node Data Types, Structures, Data Types And Structures, Data Types And Structures
@comment  node-name,  next,  previous,  up
@section Data Types

@cindex Data Types

@subsection @code{Fixed}

@tindex Fixed

 @code{Fixed} is a signed long integer.  It is used to represent decimal
numbers without using floating point arithmetics.  The decimal point is
assumed to be in the middle of the 32 bit integer, thus giving 16 bits for
the integer part of the number and 16 bits for the fraction.  The largest
number that can be stored in a @code{Fixed} is +32767.999984741, and the
lowest number is @minus{}32768.

 Example:

@example
 Decimal | Fixed
 --------+----------
  1.0    | 0x00010000
  0.5    | 0x00008000
  0.25   | 0x00004000
  0      | 0x00000000
 -0.25   | 0xffffc000
 -0.5    | 0xffff8000
 -1.0    | 0xffff0000
@end example

@subsection @code{sposition}

@tindex sposition

 @code{sposition} (stereo position) is a @code{Fixed}, and is used to
represent the stereo position of a sound.  0 is far left, 0.5 is center and
1.0 is far right.


@c ***********************************************************************
@c **** Structures *******************************************************
@c ***********************************************************************

@node Structures,  , Data Types, Data Types And Structures
@comment  node-name,  next,  previous,  up
@section Structures

@cindex Structures

@subsection @code{AHIUnitPrefs} And @code{AHIGlobalPrefs}

@tindex AHIUnitPrefs
@tindex AHIGlobalPrefs

 These structures are used in the @code{AHIU} and @code{AHIG} chunks,
respective, which are part of the settings file (@file{ENV:Sys/ahi.prefs}),
The file is read by @sc{Ahi} on each call to @code{OpenDevice()}, just
before the audio hardware is allocated.

 @code{AHIUnitPrefs} specifies the audio mode and its parameters to use for
each device unit (currently 0-3 and @code{AHI_NO_UNIT}; unit 0 is also called
@code{AHI_DEFAULT_UNIT}).

 @code{AHIGlobalPrefs} contains some global options that can be used to
gain speed on slow CPUs, the global debug level and a protection against
CPU overload.  The debug level specifies which of the functions in @sc{Ahi}
should print debugging information to the serial port (the output can be
redirected to a console window or a file with tools like @dfn{Sushi}
@footnote{Available from AmiNet, for example @*
@url{ftp://ftp.germany.aminet.org/pub/aminet/dev/debug/Sushi.lha}.}).


@c ***********************************************************************
@c **** GNU General Public License ***************************************
@c ***********************************************************************

@node  GPL, LGPL, Data Types And Structures, Top
@comment  node-name,  next,  previous,  up
@unnumbered GNU GENERAL PUBLIC LICENSE
@center Version 2, June 1991

@display
Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display

@unnumberedsec Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software---to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and
modification follow.

@iftex
@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end iftex
@ifinfo
@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end ifinfo

@enumerate 0
@item
This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License.  The ``Program'', below,
refers to any such program or work, and a ``work based on the Program''
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language.  (Hereinafter, translation is included without limitation in
the term ``modification''.)  Each licensee is addressed as ``you''.

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

@item
You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

@item
You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

@enumerate a
@item
You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.

@item
You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.

@item
If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License.  (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
@end enumerate

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

@item
You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:

@enumerate a
@item
Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,

@item
Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,

@item
Accompany it with the information you received as to the offer
to distribute corresponding source code.  (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
@end enumerate

The source code for a work means the preferred form of the work for
making modifications to it.  For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable.  However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

@item
You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

@item
You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Program or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

@item
Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

@item
If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all.  For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

@item
If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

@item
The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of this License which applies to it and ``any
later version'', you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

@item
If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

@iftex
@heading NO WARRANTY
@end iftex
@ifinfo
@center NO WARRANTY
@end ifinfo

@item
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU@.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

@item
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
@end enumerate

@iftex
@heading END OF TERMS AND CONDITIONS
@end iftex
@ifinfo
@center END OF TERMS AND CONDITIONS
@end ifinfo

@page
@unnumberedsec How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the ``copyright'' line and a pointer to where the full notice is found.

@smallexample
@var{one line to give the program's name and an idea of what it does.}
Copyright (C) 19@var{yy}  @var{name of author}

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
@end smallexample

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

@smallexample
Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  This is free software, and you are welcome
to redistribute it under certain conditions; type `show c' 
for details.
@end smallexample

The hypothetical commands @samp{show w} and @samp{show c} should show
the appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than @samp{show w} and
@samp{show c}; they could even be mouse-clicks or menu items---whatever
suits your program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a ``copyright disclaimer'' for the program, if
necessary.  Here is a sample; alter the names:

@smallexample
@group
Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written 
by James Hacker.

@var{signature of Ty Coon}, 1 April 1989
Ty Coon, President of Vice
@end group
@end smallexample

This General Public License does not permit incorporating your program into
proprietary programs.  If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library.  If this is what you want to do, use the GNU Library General
Public License instead of this License.

@c ***********************************************************************
@c **** GNU Library General Public License *******************************
@c ***********************************************************************

@node  LGPL, Concept Index, GPL, Top
@comment  node-name,  next,  previous,  up
@unnumbered GNU LIBRARY GENERAL PUBLIC LICENSE

@center Version 2, June 1991

@display
Copyright @copyright{} 1991 Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

[This is the first released version of the library GPL.  It is
 numbered 2 because it goes with version 2 of the ordinary GPL.]
@end display

@unnumberedsec Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software---to make sure the software is free for all its users.

  This license, the Library General Public License, applies to some
specially designated Free Software Foundation software, and to any
other libraries whose authors decide to use it.  You can use it for
your libraries, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if
you distribute copies of the library, or if you modify it.

  For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you.  You must make sure that they, too, receive or can get the source
code.  If you link a program with the library, you must provide
complete object files to the recipients so that they can relink them
with the library, after making changes to the library and recompiling
it.  And you must show them these terms so they know their rights.

  Our method of protecting your rights has two steps: (1) copyright
the library, and (2) offer you this license which gives you legal
permission to copy, distribute and/or modify the library.

  Also, for each distributor's protection, we want to make certain
that everyone understands that there is no warranty for this free
library.  If the library is modified by someone else and passed on, we
want its recipients to know that what they have is not the original
version, so that any problems introduced by others will not reflect on
the original authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that companies distributing free
software will individually obtain patent licenses, thus in effect
transforming the program into proprietary software.  To prevent this,
we have made it clear that any patent must be licensed for everyone's
free use or not licensed at all.

  Most GNU software, including some libraries, is covered by the ordinary
GNU General Public License, which was designed for utility programs.  This
license, the GNU Library General Public License, applies to certain
designated libraries.  This license is quite different from the ordinary
one; be sure to read it in full, and don't assume that anything in it is
the same as in the ordinary license.

  The reason we have a separate public license for some libraries is that
they blur the distinction we usually make between modifying or adding to a
program and simply using it.  Linking a program with a library, without
changing the library, is in some sense simply using the library, and is
analogous to running a utility program or application program.  However, in
a textual and legal sense, the linked executable is a combined work, a
derivative of the original library, and the ordinary General Public License
treats it as such.

  Because of this blurred distinction, using the ordinary General
Public License for libraries did not effectively promote software
sharing, because most developers did not use the libraries.  We
concluded that weaker conditions might promote sharing better.

  However, unrestricted linking of non-free programs would deprive the
users of those programs of all benefit from the free status of the
libraries themselves.  This Library General Public License is intended to
permit developers of non-free programs to use free libraries, while
preserving your freedom as a user of such programs to change the free
libraries that are incorporated in them.  (We have not seen how to achieve
this as regards changes in header files, but we have achieved it as regards
changes in the actual functions of the Library.)  The hope is that this
will lead to faster development of free libraries.

  The precise terms and conditions for copying, distribution and
modification follow.  Pay close attention to the difference between a
``work based on the library'' and a ``work that uses the library''.  The
former contains code derived from the library, while the latter only
works together with the library.

  Note that it is possible for a library to be covered by the ordinary
General Public License rather than by this special one.

@iftex
@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end iftex
@ifinfo
@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end ifinfo

@enumerate 0
@item
This License Agreement applies to any software library which
contains a notice placed by the copyright holder or other authorized
party saying it may be distributed under the terms of this Library
General Public License (also called ``this License'').  Each licensee is
addressed as ``you''.

  A ``library'' means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.

  The ``Library'', below, refers to any such software library or work
which has been distributed under these terms.  A ``work based on the
Library'' means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language.  (Hereinafter, translation is
included without limitation in the term ``modification''.)

  ``Source code'' for a work means the preferred form of the work for
making modifications to it.  For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control compilation
and installation of the library.

  Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it).  Whether that is true depends on what the Library does
and what the program that uses the Library does.
  
@item
You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
Library.

  You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.

@item
You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

@enumerate a
@item
The modified work must itself be a software library.

@item
You must cause the files modified to carry prominent notices
stating that you changed the files and the date of any change.

@item
You must cause the whole of the work to be licensed at no
charge to all third parties under the terms of this License.

@item
If a facility in the modified Library refers to a function or a
table of data to be supplied by an application program that uses
the facility, other than as an argument passed when the facility
is invoked, then you must make a good faith effort to ensure that,
in the event an application does not supply such function or
table, the facility still operates, and performs whatever part of
its purpose remains meaningful.

(For example, a function in a library to compute square roots has
a purpose that is entirely well-defined independent of the
application.  Therefore, Subsection 2d requires that any
application-supplied function or table used by this function must
be optional: if the application does not supply it, the square
root function must still compute square roots.)
@end enumerate

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Library,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Library, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Library.

In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

@item
You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library.  To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License.  (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.)  Do not make any other change in
these notices.

  Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.

  This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.

@item
You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.

  If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.

@item
A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a ``work that uses the Library''.  Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.

  However, linking a ``work that uses the Library'' with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a ``work that uses the
library''.  The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.

  When a ``work that uses the Library'' uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library.  The
threshold for this to be true is not precisely defined by law.

  If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work.  (Executables containing this object code plus portions of the
Library will still fall under Section 6.)

  Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.

@item
As an exception to the Sections above, you may also compile or
link a ``work that uses the Library'' with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.

  You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License.  You must supply a copy of this License.  If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License.  Also, you must do one
of these things:

@enumerate a
@item
Accompany the work with the complete corresponding
machine-readable source code for the Library including whatever
changes were used in the work (which must be distributed under
Sections 1 and 2 above); and, if the work is an executable linked
with the Library, with the complete machine-readable ``work that
uses the Library'', as object code and/or source code, so that the
user can modify the Library and then relink to produce a modified
executable containing the modified Library.  (It is understood
that the user who changes the contents of definitions files in the
Library will not necessarily be able to recompile the application
to use the modified definitions.)

@item
Accompany the work with a written offer, valid for at
least three years, to give the same user the materials
specified in Subsection 6a, above, for a charge no more
than the cost of performing this distribution.

@item
If distribution of the work is made by offering access to copy
from a designated place, offer equivalent access to copy the above
specified materials from the same place.

@item
Verify that the user has already received a copy of these
materials or that you have already sent this user a copy.
@end enumerate

  For an executable, the required form of the ``work that uses the
Library'' must include any data and utility programs needed for
reproducing the executable from it.  However, as a special exception,
the source code distributed need not include anything that is normally
distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies
the executable.

  It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system.  Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.

@item
You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:

@enumerate a
@item
Accompany the combined library with a copy of the same work
based on the Library, uncombined with any other library
facilities.  This must be distributed under the terms of the
Sections above.

@item
Give prominent notice with the combined library of the fact
that part of it is a work based on the Library, and explaining
where to find the accompanying uncombined form of the same work.
@end enumerate

@item
You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License.  Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License.  However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.

@item
You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Library or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.

@item
Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

@item
If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all.  For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.

If any portion of this section is held invalid or unenforceable under any
particular circumstance, the balance of the section is intended to apply,
and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

@item
If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License may add
an explicit geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not thus
excluded.  In such case, this License incorporates the limitation as if
written in the body of this License.

@item
The Free Software Foundation may publish revised and/or new
versions of the Library General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number.  If the Library
specifies a version number of this License which applies to it and
``any later version'', you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation.  If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.

@item
If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission.  For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this.  Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.

@iftex
@heading NO WARRANTY
@end iftex
@ifinfo
@center NO WARRANTY
@end ifinfo

@item
BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

@item
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
@end enumerate

@iftex
@heading END OF TERMS AND CONDITIONS
@end iftex
@ifinfo
@center END OF TERMS AND CONDITIONS
@end ifinfo

@page
@unnumberedsec How to Apply These Terms to Your New Libraries

  If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change.  You can do so by permitting
redistribution under these terms (or, alternatively, under the terms of the
ordinary General Public License).

  To apply these terms, attach the following notices to the library.  It is
safest to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least the
``copyright'' line and a pointer to where the full notice is found.

@smallexample
@var{one line to give the library's name and an idea of what it does.}
Copyright (C) @var{year}  @var{name of author}

This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Library General Public License as published
by the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.

This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Library General Public License for more details.

You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
@end smallexample

Also add information on how to contact you by electronic and paper mail.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a ``copyright disclaimer'' for the library, if
necessary.  Here is a sample; alter the names:

@smallexample
Yoyodyne, Inc., hereby disclaims all copyright interest in the library
`Frob' (a library for tweaking knobs) written by James Random Hacker.

@var{signature of Ty Coon}, 1 April 1990
Ty Coon, President of Vice
@end smallexample

That's all there is to it!


@c Part 6: The End of the Document
@c ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯

@c ***********************************************************************
@c **** Concept Index ****************************************************
@c ***********************************************************************

@node Concept Index, Data Type Index, LGPL, Top
@comment  node-name,  next,  previous,  up
@unnumbered Concept Index

@cindex Recursion

@printindex cp


@c ***********************************************************************
@c **** Data Type Index **************************************************
@c ***********************************************************************

@node Data Type Index, Function Index, Concept Index, Top
@unnumbered Data Type Index

@printindex tp


@c ***********************************************************************
@c **** Function Index ***************************************************
@c ***********************************************************************

@node Function Index, Variable Index, Data Type Index, Top
@unnumbered Function Index

@printindex fn


@c ***********************************************************************
@c **** Variable Index ***************************************************
@c ***********************************************************************

@node Variable Index,  , Function Index, Top
@unnumbered Variable Index

@printindex vr


@c ***********************************************************************
@c **** Contents *********************************************************
@c ***********************************************************************

@contents
@bye