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

  @{b}PureBasic - Sound V1.03@{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}

    @{" AllocateSoundChannels  " LINK AllocateSoundChannels}
    @{" ChangeSoundPeriod      " LINK ChangeSoundPeriod }
    @{" ChangeSoundVolume      " LINK ChangeSoundVolume}
    @{" CopySound              " LINK CopySound}
    @{" CreateSound            " LINK CreateSound}
    @{" DecodeSound            " LINK DecodeSound}
    @{" FreeSound              " LINK FreeSound}
    @{" FreeSoundChannels      " LINK FreeSoundChannels}
    @{" 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}

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


@Node AllocateSoundChannels

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

    @{b}FUNCTION@{ub}
  Use this function to allocate one or more channels.

  @{b}Channels@{ub}
  This mask specify which channels that should be
  allocated.

  1 = try to allocate channel 0
  2 = try to allocate channel 1
  4 = try to allocate channel 2
  8 = try to allocate channel 3

  When added together:

   9 = try to allocate channel 0 and 3
  15 = try to allocate all channels

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


@Node ChangeSoundPeriod

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.w = ChangeSoundPeriod(@{b}#Sound@{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}#Sound@{ub}
  The sound to change period for.

  @{b}Period@{ub}
  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}#Sound@{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}#Sound@{ub}
  The sound to change volume for.

  @{b}Volume@{ub}
  The new volume value.

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


@Node CopySound

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.l = CopySound(@{b}#Sound@{ub}.w,@{b}#Sound@{ub}.w)

    @{b}FUNCTION@{ub}
  This function make a complete copy out of
  another #Sound object.

  @{b}#Sound@{ub}
  The sound to copy.

  @{b}#Sound@{ub}
  The new sound.

  @{b}Result@{ub}
  If this is TRUE the copy of the #Sound have
  been done else it is FALSE.
@EndNode


@Node CreateSound

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.l = CreateSound(@{b}#Sound@{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}#Sound@{ub}
  The sound 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 #Sound object are created else
  it is FALSE.
@EndNode


@Node DecodeSound

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

    @{b}FUNCTION@{ub}
  This function initialize a #Sound object from the
  IFF sound file included into 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}#Sound@{ub}
  The sound to use.

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

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


@Node FreeSound

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

    @{b}STATEMENT@{ub}
  This statement free 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 by that a #Sound object that is initialized
  with DecodeSound() is valid until the object is initialized
  again with LoadSound() or DecodeSound().  Which mean, such
  object could never be freed.

  @{b}#Sound@{ub}
  The sound to free.
@EndNode


@Node FreeSoundChannels

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

    @{b}FUNCTION@{ub}
  This function frees one or more channels.

  @{b}Channels@{ub}
  This mask specify which channels that should
  be freed.

  1 = free channel 0
  2 = free channel 1
  4 = free channel 2
  8 = free channel 3

  When added together:

   9 = free both channel 0 and 3
  15 = free all channels

  @{b}Result@{ub}
  If this mask is TRUE it show which channels that are
  freed else it is FALSE and which mean; they are not
  freed because they have never been allocated.
@EndNode


@Node GetSoundLength

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.l = GetSoundLength(@{b}#Sound@{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}#Sound@{ub}
  The sound to use.

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


@Node InitSound

    @{b}SYNTAX@{ub}
  @{b}Result@{ub}.w = InitSound(@{b}Sounds@{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}Sounds@{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}#Sound@{ub}.w,@{b}FileName@{ub}$)

    @{b}FUNCTION@{ub}
  Use this function to initialize a #Sound object from an IFF
  sound file 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}#Sound@{ub}
  The sound to use

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

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


@Node PeekSoundData

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

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

  @{b}#Sound@{ub}
  The sound to use.

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

  @{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}#Sound@{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}#Sound@{ub}
  The sound 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}#Sound@{ub}.w,@{b}Position@{ub}.l,@{b}Data@{ub}.b)

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

  @{b}#Sound@{ub}
  The sound to use.

  @{b}Position@{ub}
  This specify where in the sound data the write
  should be done.

  @{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}#Sound@{ub}.w,@{b}FileName@{ub}$)

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

  @{b}#Sound@{ub}
  The sound to save.

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

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


@Node SetSoundChannels

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

    @{b}STATEMENT@{ub}
  This statement set channel mask for the #Sound that
  is used when the sound is played.

  Channel mask are set to 15 when the #Sound is
  initialized with LoadSound() or DecodeSound().

  @{b}#Sound@{ub}
  The sound 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}#Sound@{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}#Sound@{ub}
  The sound 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}#Sound@{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}#Sound@{ub}
  The sound 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}#Sound@{ub}.w)

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

  @{b}#Sound@{ub}
  The sound to stop.
@EndNode