@DATABASE "Sound"
@AUTHOR "Paul Manias"
@NODE "Main" "Sound Documentation"

Name:         @{"SOUND.GPI" LINK "Functions"} AUTODOC
Version:      0.7 Beta.
Date:         3 July 1997
Author:       Paul Manias
Copyright:    DreamWorld Productions, 1996-1997.  All rights reserved.
Notes:        This  document is still being written and will contain errors
              in  a  number  of  places.   The information within cannot be
	      treated as official until this autodoc reaches version 1.0.

@EndNode
---------------------------------------------------------------------------
@NODE "Functions" "Sound Functions"

 @{b}STRUCTURES@{ub}
 @{"Sound" LINK "Sound"}

 @{b}FUNCTIONS@{ub}
 @{"AllocAudio()"    LINK "AllocAudio()"}
 @{"AllocSoundMem()" LINK "AllocSoundMem()"}
 @{"FreeAudio()"     LINK "FreeAudio()"}
 @{"InitSound()"     LINK "InitSound()"}
 @{"FreeSound()"     LINK "FreeSound()"}
 @{"FreeSoundMem()"  LINK "FreeSoundMem()"}
 @{"GetSound()"      LINK "GetSound()"}
 @{"CheckChannel()"  LINK "CheckChannel()"}
 @{"PlaySound()"     LINK "PlaySound()"}
 @{"PlaySoundPri()"  LINK "PlaySoundPri()"}
 @{"SetVolume()"     LINK "SetVolume()"}
 @{"FadeVolume()"    LINK "FadeVolume()"}
 @{"InitPlayer()"    LINK "InitPlayer()"}
 @{"PlayMOD()"       LINK "PlayMOD()"}
 @{"StopPlayer()"    LINK "StopSTPlayer()"}

@EndNode
---------------------------------------------------------------------------
@NODE  "Sound" "Structure: Sound"

Name:    Sound
Version: 1
ID Code: SM
Type:    Simple

@{b}@{u}DESCRIPTION@{uu}@{ub}
The  purpose of the Sound structure is to provide a standard interface that
any  GMS  program  can use to load a sound file.  The advantage is that the
source  sound  can  be  in  any file format currently recognised by GMS, so
effectively  the  program  in question will be able to support file formats
that it does not immediately recognise.

Some functions using the Sound structure are:

	GetSound()
	InitSound()
	FreeSound()
	PlaySound()


@{b}STRUCTURE@{ub}
The Sound structure consists of the following public fields:

	@{"Attrib   " LINK SND_Attrib   } Sound attributes.
	@{"Channel  " LINK SND_Channel  } Channel.
	@{"Data     " LINK SND_Data     } Address of sample data.
	@{"File     " LINK SND_File     } Where the sound comes from.
	@{"Frequency" LINK SND_Frequency} Sampled frequency.
	@{"Header   " LINK SND_Header   } Sample info header, if any.
	@{"Length   " LINK SND_Length   } Length of sample data in bytes.
	@{"Octave   " LINK SND_Octave   } Octave/Note setting.
	@{"Priority " LINK SND_Priority } Priority.
	@{"Volume   " LINK SND_Volume   } Volume of sample (1 - 100).

@EndNode
---------------------------------------------------------------------------
@NODE "SND_Channel" "Structure: Sound"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Channel
On Change:   Dynamic
Structure:   Sound
Status:      Read/Write
Inheritance: None

@{b}@{u}DESCRIPTION@{uu}@{ub}
Specifies  the  channel  that you want to play through.  Acceptable channel
numbers range from 1 to whatever is specified in the AmtChannels field.  If
you  don't  care  what channel the sound plays through, specify ALLCHANNELS
(-1)  here.   Note  that by specifying ALLCHANNELS you automatically enable
the  Speaker  flags, SLEFT, SRIGHT and SFORCE.

@EndNode
---------------------------------------------------------------------------
@NODE "SND_Priority" "Structure: Sound"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Priority
On Change:   Dynamic
Structure:   Sound
Status:      Read/Write
Inheritance: None

@{b}@{u}DESCRIPTION@{uu}@{ub}
The  priority  of  your  sound  goes  here.   This  field  is  used  by the
PlaySoundPri()  function to determine if your sound should be played if the
destination Channel is currently busy.  Naturally, higher values are played
over samples with lower values.

@EndNode
---------------------------------------------------------------------------
@NODE "SND_Header" "Structure: Sound"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Header
On Change:   Cannot change after initialisation.
Structure:   Sound
Status:      IWrite only.
Inheritance: 

@{b}@{u}DESCRIPTION@{uu}@{ub}
Points  to  the  very  start of the sample, which in most cases will be the
something  like  an IFF 8SVX header.  If the sample data is RAW then simply
point to the start of the data here.

@EndNode
---------------------------------------------------------------------------
@NODE "SND_Data" "Structure: Sound"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Data
On Change:   Cannot change after initialisation.
Structure:   Sound
Status:      Read/IWrite
Inheritance: Header

@{b}@{u}DESCRIPTION@{uu}@{ub}
This field points to the actual sample data that is going to be played.

@EndNode
---------------------------------------------------------------------------
@NODE "SND_Length" "Structure: Sound"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Length
On Change:   Cannot change after initialisation.
Structure:   Sound
Status:      Read/IWrite
Inheritance: Header

@{b}@{u}DESCRIPTION@{uu}@{ub}
The  length  of the sample data in bytes.

@EndNode
---------------------------------------------------------------------------
@NODE "SND_Octave" "Structure: Sound"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Octave
On Change:   Dynamic
Structure:   Sound
Status:      Read/Write
Inheritance: Header

@{b}@{u}DESCRIPTION@{uu}@{ub}
The  octave  at  which  to  play this sample.  The highest pitched value is
OCT_G0S, the lowest is OCT_A7S.  There are about 94 available settings, see
games/sound.i to look at the complete list.

@EndNode
---------------------------------------------------------------------------
@NODE "SND_Volume" "Structure: Sound"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Volume
On Change:   Dynamic
Structure:   Sound
Status:      Read/Write
Inheritance: Header

@{b}@{u}DESCRIPTION@{uu}@{ub}
The volume of the sound, which lies in the range 0 - 100.  A volume of zero
will not be heard, a volume of 100 is the loudest.

@EndNode
---------------------------------------------------------------------------
@NODE "SND_Attrib" "Structure: Sound"

@{b}@{u}FIELD@{uu}@{ub}
Name:        Attrib
On Change:   Cannot change after initialisation.
Structure:   Sound
Status:      Read/IWrite
Inheritance: None

@{b}@{u}DESCRIPTION@{uu}@{ub}
Specifies the attributes for the sound.

  @{u}SBIT8@{uu}
  Sound data is 8 bit (only set this if raw).

  @{u}SBIT16@{uu}
  Sound data is 16 bit (only set this if raw).

  @{u}SMODVOL@{uu}
  Modulates the volume with the next channel.

  @{u}SMODPER@{uu}
  Modulate the sound's period with the next channel.

  @{u}SREPEAT@{uu}
  Repeats the sample forever.

@EndNode
---------------------------------------------------------------------------
@NODE "SND_File" "Structure: Sound"

@{b}@{u}FIELD@{uu}@{ub}
Name:        File
On Change:   Cannot change after initialisation.
Structure:   Sound
Status:      Read/IWrite
Inheritance: None

@{b}@{u}DESCRIPTION@{uu}@{ub}
If  your  sound  is located on disk, place a pointer to the file name here.
This  will  cause InitSound() to load the sound data in for you (via a call
to  SmartLoad())  and  fill in the Header and Data fields.  The rest of the
initialisation procedure will then be carried out.

@EndNode
---------------------------------------------------------------------------
@NODE "AllocAudio()" "Sound/AllocAudio"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      AllocAudio()
Short:     Attempt to allocate the audio channels.
Assembler: ErrorCode = AllocAudio()
C/C++:     LONG AllocAudio(void)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Attempts  to  allocate  all  the  audio  channels for your own use.  If the
function  cannot  get  the  channels,  it  will return with an errorcode of
ERR_INUSE.   If  the  call is successful (NULL) then you can safely use all
the sound functions within GMS.

This  function  should  be  called  at  the  start  of your program, and if
successful you must call FreeAudio() before your program exits.

@{b}RESULT@{ub}
ErrorCode - NULL if successful or ERR_INUSE if unsuccessful.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"FreeAudio" LINK "FreeAudio()"}

@EndNode
---------------------------------------------------------------------------
@NODE "FreeAudio()" "Sound/FreeAudio"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      FreeAudio()
Short:     Free the audio channels for system use.
Assembler: FreeAudio()
C/C++:     void FreeAudio(void)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Frees the audio channels so that the system can use them again.  You cannot
make use of any of the audio channels after calling this function.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"AllocAudio" LINK "AllocAudio()"}

@EndNode
---------------------------------------------------------------------------
@NODE "InitSound()" "Sound/InitSound"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      InitSound()
Short:     Initialise a sound structure for the play routines.
Assembler: Sound = InitSound(APTR [a0])
C/C++:     struct Sound * InitSound(APTR Sound *)
           struct Sound * InitSoundTags(ULONG tag, ...)

@{b}@{u}DESCRIPTION@{uu}@{ub}
This  function  will  initialise a sound for use in the play routines.  Its
main  job  is  to load and assess the sound header, and fill in any missing
fields.  It can also unpack sounds in some cases.

If  the following fields in the Sound structure are detected as being NULL,
InitSound() will fill them in for you:

  Data
  Length
  Period
  Volume

If you don't want some or all of these fields written too, simply fill them
in  before-hand.   This  is  imperative  if the sound is in RAW format, for
obvious reasons.

Lists  and  object  lists are fully supported by this function, just pass a
pointer to one of these instead of a Sound.  (See lists).

@{b}@{u}NOTE@{uu}@{ub}
If  the sound is in RAW format, then this function will not be able to do
much, so you should set most of the fields yourself.

@{b}@{u}INPUTS@{uu}@{ub}
Sound - Pointer to Sound structure, list, object list or tag list.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"FreeSound" LINK "FreeSound()"}

@EndNode
---------------------------------------------------------------------------
@NODE "FreeSound()" "Sound/FreeSound"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      FreeSound()
Short:     Free any allocations made in an initialised sound.
Assembler: FreeSound(Sound [a0])
C/C++:     void FreeSound(struct Sound *)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Frees any allocations made in the initialisation of a Sound structure.  You
have  to  call  this  function  at  some point for every initialised Sound,
otherwise resources may be withheld on the exit of your program.

If  the  structure  was  allocated  via  GetSound() or a tag list, then the
structure  itself will be freed from memory (you will not be allowed to use
it any longer).

This function is fully supportive of lists and object lists.

@{b}@{u}INPUTS@{uu}@{ub}
Sound - Pointer to an intialised sound structure.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"InitSound" LINK "InitSound()"}

@EndNode
---------------------------------------------------------------------------
@NODE "CheckChannel()" "Sound/CheckChannel"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      CheckChannel()
Short:     Checks the current activity of a sound channel.
Assembler: Status = CheckChannel(Channel [d0])
C/C++:     WORD CheckChannel(WORD Channel)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Checks the specified channel to see if it has any data playing through it.

@{b}@{u}INPUTS@{uu}@{ub}
Channel - Either 1, 2, 3 or 4.

@{b}RESULT@{ub}
Status - The current status of the channel, a result of NULL indicates that
         the channel is free.  A result of 1 indicates that the channel is
	 busy.

@EndNode
---------------------------------------------------------------------------
@NODE "PlaySound()" "Sound/PlaySound"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      PlaySound()
Short:     Play a sound through an audio channel.
Assembler: PlaySound(Sound [a0])
C/C++:     void PlaySound(struct Sound *)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Plays  a  sound  according  to  the  settings in the sound structure.  This
function executes immediately, and ignores all channel/sound priorities.

You must have initialised the sound structure before calling this function.

@{b}@{u}INPUTS@{uu}@{ub}
Sound - Pointer to a valid sound structure.

@{b}@{u}SEE ALSO@{uu}@{ub}
PlaySoundPri

@EndNode
---------------------------------------------------------------------------
@NODE "PlaySoundPri()" "Sound/PlaySoundPri"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      PlaySoundPri()
Short:     Play a sound if it can equal or better a channel's priority.
Assembler: PlaySoundPri(Sound [a0])
C/C++:     void PlaySoundPri(struct Sound *)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Plays  a  sound  according  to  the  settings in the sound structure, IF it
equals or betters the channel's current priority setting.

Prioritisation  of  sounds  allows  you  to play sound effects according to
their  importance.  Make sure that you take care in ordering your sounds so
that they play effectively!

It is recommended that you use CHANNEL_ALL in the SND_Channel field so that
your game makes maximum use of all the available sound channels.

@{b}@{u}INPUTS@{uu}@{ub}
Sound - Pointer to a valid sound structure.

@{b}@{u}SEE ALSO@{uu}@{ub}
PlaySound, @{"games/games.i" LINK "INCLUDES:games/games.i" 1}

@EndNode
-----------------------------------------------------------------------------
@NODE "AllocSoundMem()" "Sound/AllocSoundMem"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      AllocSoundMem()
Short:     Allocate memory for sample playback.
Assembler: Memory = AllocSoundMem(Size [d0])
C/C++:     APTR AllocSoundMem(LONG Size)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Allocates a block of memory suitable for playing sound samples.

@{b}@{u}INPUTS@{uu}@{ub}
Size - The Size of the memory to allocate.

@{b}RESULT@{ub}
Memory - Pointer to the allocated memory.  All audio memory is formatted
	 with 0's when allocated.  Returns NULL if error.

@{b}@{u}SEE ALSO@{uu}@{ub}
FreeMemBlock

@EndNode
-----------------------------------------------------------------------------
@NODE "GetSound()" "Sound/GetSound"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      GetSound()
Short:     Gets the latest version of the sound structure.
Assembler: Sound = GetSound()
C/C++:     struct Sound * GetSound(void);

@{b}@{u}DESCRIPTION@{uu}@{ub}
Allocates the latest version of the GMS sound structure and returns it back
to  you.   The structure fields will be empty so that you can fill them out
to suit your requirements.  Before your program exits you will need to free
the structure, this is automatically done in the FreeSound() function.

You  have  to  use  this  function  if  you do not want to use tag lists to
initialise  your  sound  (remember  that  it  is illegal to compile and use
pre-initialised structures in GMS programs).

@{b}RESULT@{ub}
Sound - Pointer to a new sound structure.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"InitSound" LINK "InitSound()"}

@EndNode
-----------------------------------------------------------------------------
@NODE "FreeSoundMem()" "Sound/FreeSoundMem"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      FreeSoundMem()
Short:     Frees a block of sound memory.
Assembler: FreeSoundMem(MemBlock [d0])
C/C++:     void FreeSoundMem(APTR MemBlock);

@{b}@{u}DESCRIPTION@{uu}@{ub}
Frees a block of sound memory.

@{b}@{u}INPUT@{uu}@{ub}
MemBlock - Pointer to a Sound memory block allocated from AllocSoundMem() or
	   AllocMemBlock()

@EndNode
-----------------------------------------------------------------------------
@NODE "()" "Sound/"

@{b}@{u}FUNCTION@{uu}@{ub}

@{b}SYNOPSIS@{ub}

@{b}@{u}DESCRIPTION@{uu}@{ub}

@{b}@{u}INPUT@{uu}@{ub}

@{b}RESULT@{ub}

@{b}@{u}SEE ALSO@{uu}@{ub}

@EndNode