@DATABASE Sound V1.00
$VER: PureBasic - Sound library V1.00 (05.10.1999) © Fantaisie Software
@NODE MAIN "Sound V1.00"

  @{b}PureBasic - Sound V1.00@{ub}

    Managing sounds will never be so easy and so fast
    than with this library. Believe us, we push the
    Amiga hardware to the max, to allow system compliant
    but instant sound replay. It simply use the 4 stereo
    audio channels for efficient output. The sound format
    is the IFF/8SVX, standard of the Amiga.

  @{b}Commands summary:@{ub}

    @{" ChangeSoundPeriod " LINK ChangeSoundPeriod }
    @{" ChangeSoundVolume " LINK ChangeSoundVolume}
    @{" CreateSound       " LINK CreateSound}
    @{" DecodeSound       " LINK DecodeSound}
    @{" FreeSound         " LINK FreeSound}
    @{" GetSoundLength    " LINK GetSoundLength}
    @{" InitSound         " LINK InitSound}
    @{" LoadSound         " LINK LoadSound}
    @{" PeekSoundData     " LINK PeekSoundData}
    @{" PlaySound         " LINK PlaySound}
    @{" PokeSoundData     " LINK PokeSoundData}
    @{" SaveSound         " LINK SaveSound}
    @{" SetSoundChannels  " LINK SetSoundChannels}
    @{" SetSoundPeriod    " LINK SetSoundPeriod}
    @{" SetSoundVolume    " LINK SetSoundVolume}
    @{" SoundFilter       " LINK SoundFilter}
    @{" StopSound         " LINK StopSound}
    @{" UseSoundChannels  " LINK UseSoundChannels}

    @{" Sound Demo " LINK PureBasic:Examples/Sources/Sound.pb/Main}
@ENDNODE


@Node ChangeSoundPeriod

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.w = ChangeSoundPeriod(@{b}#Obj@{ub}.w,@{b}Period@{ub}.w)

    @{b}FUNCTION@{ub}
  Use this function to change the period when the sound
  is actually played.

  The Period set in the Sound Object, that is used when
  the sound is started, is not affected with this call.

  @{b}#Obj@{ub}
  The Object to change period for.

  @{b}Period@{ub}
  This is the new period value.

  @{b}Result@{ub}
  This mask show which are the affected channels that the period
  is changed for.
@EndNode


@Node ChangeSoundVolume

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.w = ChangeSoundVolume(@{b}#Obj@{ub}.w,@{b}Volume@{ub}.w)

    @{b}FUNCTION@{ub}
  Use this function to change the volume when the sound
  is actually played.

  The Volume set in the Sound Object, that is used when
  the sound is started, is not affected with this call.

  @{b}#Obj@{ub}
  The Object to change volume for.

  @{b}Volume@{ub}
  This is the new volume value.

  @{b}Result@{ub}
  This mask show which are the affected channels that the
  volume is changed for.
@EndNode


@Node CreateSound

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.l = CreateSound(@{b}#Obj@{ub}.w,@{b}Length@{ub}.l)

    @{b}FUNCTION@{ub}
  This function create a new Sound Object and all of it's
  sound data is set to zero. Period, Volume and Channels
  are also set to zero.

  To read and write the sound data use PeekSoundData()
  and PokeSoundData(). Period, Volume and Channels have
  to be set with the appropriate statement.

  @{b}#Obj@{ub}
  The Object to create.

  @{b}Length@{ub}
  The length of the sound data.

  It's useless to specify any value higher than 128K
  here as the Amiga hardware doesn't support it.

  @{b}Result@{ub}
  If this is TRUE the Object could be created else
  it is FALSE.
@EndNode


@Node DecodeSound

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.w = DecodeSound(@{b}#Obj@{ub}.w,@{b}Pointer@{ub}.l)

    @{b}FUNCTION@{ub}
  This function initialize a Sound Object from the
  IFF sound stored inside the program.

  * Period are set to value taken from IFF file.
  * Volume is set to 64.
  * Channels is set to 15.

  If the Sound Object is already initialized it must
  first be freed with a call to FreeSound() else it
  stay in memory and there will be no possibility to
  play it.

  @{b}#Obj@{ub}
  The Object to use.

  @{b}Pointer@{ub}
  A pointer to the IFF sound.

  @{b}Result@{ub}
  This is TRUE if the Sound Object could be initialized
  from the included IFF sound else it is FALSE.
@EndNode


@Node FreeSound

    @{b}SYNTAX@{ub}
  FreeSound(@{b}#Obj@{ub}.w)

    @{b}STATEMENT@{ub}
  This statement frees a Sound Object that is initialized
  with LoadSound() or DecodeSound().

  If no fast memory is availible then the program end up in
  chip memory and a Sound Object that is initialized with
  DecodeSound() is valid until the Object is initialized
  with; LoadSound(); or again DecodeSound(), another
  included IFF sound is used.
  Which mean, such Object could never be freed.

  @{b}#Obj@{ub}
  The Object to free.
@EndNode


@Node GetSoundLength

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.l = GetSoundLength(@{b}#Obj@{ub}.w)

    @{b}FUNCTION@{ub}
  This function gets the length of a Sound Object.

  Use it for calculations so PeekSoundData() and
  PokeSoundData() not read and write outside of
  the actual sound data.

  @{b}#Obj@{ub}
  The Object to use.

  @{b}Result@{ub}
  The length of the sound data.
@EndNode


@Node InitSound

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.w = InitSound(@{b}Objects@{ub}.l)

    @{b}FUNCTION@{ub}
  This function is the initroutine, it set up all needed stuff,
  and it must be called befor all other functions.
  It could only be called once.

  @{b}Objects@{ub}
  This is how many Sound Objects that is wanted.

  @{b}Result@{ub}
  If this is TRUE the call was successful else it is FALSE and
  then no other functions could be called.
@EndNode


@Node LoadSound

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.b = LoadSound(@{b}#Obj@{ub}.w,@{b}FileName@{ub}$)

    @{b}FUNCTION@{ub}
  Use this function to initialize a Sound Object from an IFF
  sound stored on disk.

  * Period are set to value taken from IFF file.
  * Volume is set to 64.
  * Channels is set to 15.

  If the Sound Object is already initialized it must first be
  freed with a call to FreeSound() else it stay in memory and
  there will be no possibility to play it.

  @{b}#Obj@{ub}
  The Object to use

  @{b}FileName@{ub}
  This is the full path to the IFF sound.

  @{b}Result@{ub}
  It will be TRUE if the Sound Object could be initialized from
  the specified IFF sound else it is FALSE.
@EndNode


@Node PeekSoundData

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.b = PeekSoundData(@{b}#Obj@{ub}.w,@{b}Position@{ub}.l)

    @{b}FUNCTION@{ub}
  This function read some sound data from a Sound Object.

  @{b}#Obj@{ub}
  The Object to use.

  @{b}Position@{ub}
  This is where in the Sound Object the data should be read.

  @{b}Result@{ub}
  The data read, it could range between -128 and 127.
@EndNode


@Node PlaySound

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.w = PlaySound(@{b}#Obj@{ub}.w,@{b}Repeat@{ub}.w)

    @{b}FUNCTION@{ub}
  This function play the specified Sound Object and it use
  the values; Period, Volume and Channels set in the Object.

  @{b}#Obj@{ub}
  The Object to play.

  @{b}Repeat@{ub}
  To have the sound played one or more times and then stoped
  set this to a positive none zero value, if the sound should
  be repeated forever set it to minus.

  @{b}Result@{ub}
  This mask show the actual channels that is used for this
  sound, zero indicate that the sound is not played.
@EndNode


@Node PokeSoundData

    @{b}SYNTAX@{ub}
  PokeSoundData(@{b}#Obj@{ub}.w,@{b}Position@{ub}.l,@{b}Data@{ub}.b)

    @{b}STATEMENT@{ub}
  This statement write some data to a Sound Object.

  @{b}#Obj@{ub}
  The Object to use.

  @{b}Position@{ub}
  This specify where in the Sound Object the data
  should be written.

  @{b}Data@{ub}
  The data to write, should range from -128 to 127.
@EndNode


@Node SaveSound

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.b = SaveSound(@{b}#Obj@{ub}.w,@{b}FileName@{ub}$)

    @{b}FUNCTION@{ub}
  This function save a Sound Object to disk as a IFF sound.

  @{b}#Obj@{ub}
  The Object to save.

  @{b}FileName@{ub}
  This is the full path to where the IFF sound should be saved.

  @{b}Result@{ub}
  It will be TRUE if the Sound Object could be saved to disk as
  the specified IFF sound else it is FALSE.
@EndNode


@Node SetSoundChannels

    @{b}SYNTAX@{ub}
  SetSoundChannels(@{b}#Obj@{ub}.w,@{b}Channels@{ub}.w)

    @{b}STATEMENT@{ub}
  This statement set Channels in the Sound Object that
  is used when the sound is played.

  The Channels are set to 15 when the Sound Object is
  initialized with LoadSound() or DecodeSound().

  @{b}#Obj@{ub}
  The Object to set channels for.

  @{b}Channels@{ub}
  This is a mask that specify which channels that should
  be used for this Object.

  1 = use only channel 0
  2 = use only channel 1
  4 = use only channel 2
  8 = use only channel 3

  When added together:

   5 = use channel 0 and 2
  15 = use all channels
@EndNode


@Node SetSoundPeriod

    @{b}SYNTAX@{ub}
  SetSoundPeriod(@{b}#Obj@{ub}.w,@{b}Period@{ub}.w)

    @{b}STATEMENT@{ub}
  This statement set Period in the Sound Object that
  is used when the sound is played.

  The Period will be correctly set to the right value,
  taken from IFF file, when Sound Object is initialized
  with LoadSound() or DecodeSound().

  @{b}#Obj@{ub}
  The Object to set period for.

  @{b}Period@{ub}
  The period, it should be the final value as no
  calculations at all is done on this.
@EndNode


@Node SetSoundVolume

    @{b}SYNTAX@{ub}
  SetSoundVolume(@{b}#Obj@{ub}.w,@{b}Volume@{ub}.w)

    @{b}STATEMENT@{ub}
  This statement set Volume in the Sound Object
  that is used when the sound is played.

  The Volume are set to 64 when the Sound Object is
  initialized with LoadSound() or DecodeSound().

  @{b}#Obj@{ub}
  The Object to set volume for.

  @{b}Volume@{ub}
  The volume, should range between 0 and 64.
@EndNode


@Node SoundFilter

    @{b}SYNTAX@{ub}
  SoundFilter(@{b}ON/OFF@{ub})

    @{b}STATEMENT@{ub}
  This statement turn the audiofiler on or off.

  @{b}ON/OFF@{ub}
  Set this to TRUE to turn the audiofilter ON or
  set it to FALSE to turn audiofiler OFF.
@EndNode


@Node StopSound

    @{b}SYNTAX@{ub}
  StopSound(@{b}#Obj@{ub}.w)

    @{b}STATEMENT@{ub}
  Use this statement to stop a sound.

  @{b}#Obj@{ub}
  The Object to stop.
@EndNode


@Node UseSoundChannels

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.w = UseSoundChannels(@{b}Channels@{ub}.w)

    @{b}FUNCTION@{ub}
  This function frees and allocate channels, both that in
  the same call.

  Lets say:
  If all channels are successfully allocated on first call,
  Channels set to 15, and then if channel 2 and 3 should
  be freed then have Channels set to 3 on second call,
  channel 0 and 1 stays allocated; 2 and 3 are freed.

  @{b}Channels@{ub}
  This is the wanted channels which also say what
  channels to free.

  @{b}Result@{ub}
  If this mask is TRUE it show which channels that could
  be allocated else it is FALSE and the wanted channels
  are not allocated.
@EndNode