@DATABASE "Sound"
@AUTHOR "Paul Manias"
@NODE "Main" "Sound.GPI"

Name:         @{"SOUND.GPI" LINK "GPIFunctions"} AUTODOC
Version:      0.6 Beta.
Date:         2 May 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 "GPIFunctions" "Sound.GPI Functions"

 @{b}SOUND.GPI@{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()"}
 @{"PlaySoundDAC1()"    LINK "PlaySoundDACX()"}
 @{"PlaySoundDAC2()"    LINK "PlaySoundDACX()"}
 @{"PlaySoundDAC3()"    LINK "PlaySoundDACX()"}
 @{"PlaySoundDAC4()"    LINK "PlaySoundDACX()"}
 @{"PlaySoundPri()"     LINK "PlaySoundPri()"}
 @{"PlaySoundPriDAC1()" LINK "PlaySoundPriDACX()"}
 @{"PlaySoundPriDAC2()" LINK "PlaySoundPriDACX()"}
 @{"PlaySoundPriDAC3()" LINK "PlaySoundPriDACX()"}
 @{"PlaySoundPriDAC4()" LINK "PlaySoundPriDACX()"}
 @{"SetVolume()"        LINK "SetVolume()"}
 @{"FadeVolume()"       LINK "FadeVolume()"}
 @{"InitPlayer()"       LINK "InitPlayer()"}
 @{"PlayMOD()"          LINK "PlayMOD()"}
 @{"StopPlayer()"       LINK "StopSTPlayer()"}

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

@{b}NAME@{ub}	AllocAudio -- Attempt to allocate the audio channels.

@{b}SYNOPSIS@{ub}
	ErrorCode = AllocAudio()
	   d0

	ULONG AllocAudio(void)

@{b}FUNCTION@{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}SEE ALSO@{ub}
	@{"FreeAudio" LINK "FreeAudio()"}

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

@{b}NAME@{ub}	FreeAudio -- Free the audio channels for system use.

@{b}SYNOPSIS@{ub}
	FreeAudio()

	void FreeAudio(void)

@{b}FUNCTION@{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}SEE ALSO@{ub}
	@{"AllocAudio" LINK "AllocAudio()"}

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

@{b}NAME@{ub}	InitSound -- Initialise a sound structure for the play routines.

@{b}SYNOPSIS@{ub}
	Sound = InitSound(Sound/TagList/List/ObjectList)
	  d0                          a0

	struct Sound * InitSound(struct Sound *)

	struct Sound * InitSoundTags(ULONG tag, ...)

@{b}FUNCTION@{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}NOTE@{ub}	If  the sound is in RAW format, then this function will have little
	effect, so you should set most of the fields yourself.

@{b}INPUTS@{ub}	Sound - Pointer  to a single sound structure, or for multiple
	  initialisations, a list of Sound's.

	@{b}SAM_Channel@{ub}
	The  channel  that  you  want  to play through.  Acceptable channel
	numbers are 0, 1, 2 and 3 (a total of 4 available channels).

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

	@{b}SAM_Header@{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.

	@{b}SAM_Data@{ub}
	This  field  points  to the actual data that is going to be played.
	InitSound()  will  fill this field in for you if you initialise it
	to 0.

	@{b}SAM_Length@{ub}
	The  length of the sample data in words.  This field will be filled
	in for you if the sound has a recognised header (eg IFF).

	@{b}SAM_Octave@{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.

	@{b}SAM_Volume@{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.

	@{b}SAM_Attrib@{ub}
	Specifies the attributes for the sound.

	  SBIT8   - Sound data is 8 bit (only set this if raw).

	  SBIT16  - Sound data is 16 bit (only set this if raw).

	  SMODVOL - Modulates the volume with the next channel.

	  SMODPER - Modulate the sound's period with the next channel.

	  SREPEAT - Repeats the sample forever.

	@{b}SAM_File@{ub}
	If your sound is contained on disk, place a pointer to the filename
	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.

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

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

@{b}NAME@{ub}	FreeSound -- Free any allocations made in an initialised sound.

@{b}SYNOPSIS@{ub}
	FreeSound(Sound)
	           a0

	void FreeSound(struct Sound *)

@{b}FUNCTION@{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}INPUTS@{ub}	Sound - Pointer to an intialised sound structure.

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

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

@{b}NAME@{ub}	CheckChannel -- Checks the current activity of a sound channel.

@{b}SYNOPSIS@{ub}
	Status = CheckChannel(Channel)
	  d0                    d0.w

	UWORD CheckChannel(UWORD Channel)

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

@{b}INPUTS@{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.GPI/PlaySound"

@{b}NAME@{ub}	PlaySound -- Play a sound through an audio channel.

@{b}SYNOPSIS@{ub}
	PlaySound(Sound)
	           a0

	void PlaySound(struct Sound *)

@{b}FUNCTION@{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}INPUTS@{ub}	Sound - Pointer to a valid sound structure.

@{b}SEE ALSO@{ub}
	PlaySoundDACx, PlaySoundPri, PlaySoundPriDACx

@EndNode
---------------------------------------------------------------------------
@NODE "PlaySoundDACX()" "Sound.GPI/PlaySoundDACx"

@{b}NAME@{ub}	PlaySoundDACx -- Play a sound with ignorance to channel priorities.

@{b}SYNOPSIS@{ub}
	PlaySoundDACx(Sound)
	               a0

	void PlaySoundDACx(struct Sound *)

	Where  'x'  is  either 1, 2, 3 or 4, which is a direct reference to
	the channel number.

@{b}FUNCTION@{ub}
	DAC  stands  for Direct Access to Channel.  This is the fastest way
	to  play  a  sound  as  it  goes  directly  to that channel's sound
	routine,  but  it  is  not  very  easy to work with.  This function
	exists  for  intelligently  changing  from  full channel access for
	sound effects, to one channel access while music is playing.

	When  setting  up your sounds you should make sure that you use all
	four  channels  in  your  structures.  If the music is off, use the
	normal PlaySoundPri() function.  If the music is on, and if it uses
	all  but one of the channels, use this function to re-route all the
	sound effects through the spare channel.

@{b}NOTE@{ub}	This  function  ignores  sound  priorities, and will play the sound
	regardless of wether the channel is busy or not.

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

@{b}SEE ALSO@{ub}
	PlaySound, PlaySoundPri, PlaySoundPriDACx, @{"games/games.i" LINK "INCLUDES:games/games.i/Main"}

@EndNode
---------------------------------------------------------------------------
@NODE "PlaySoundPriDACX()" "Sound.GPI/PlaySoundPriDACx"

@{b}NAME@{ub}	PlaySoundPriDACx -- Play a sound ignoring the setting in SAM_Channel.

@{b}SYNOPSIS@{ub}
	PlaySoundPriDACx(Sound)
	                  a0

	void PlaySoundPriDACx(struct Sound *)

	Where  'x'  is  either 1, 2, 3 or 4, which is a direct reference to
	the channel number.

@{b}FUNCTION@{ub}
	DAC  stands  for Direct Access to Channel.  This is the fastest way
	to  play  a prioritised sound as it goes directly to that channel's
	sound routine, but it is not very easy to work with.  This function
	exists  for  intelligently  changing  from  full channel access for
	sound effects, to one channel access while music is playing.

	When  setting  up your sounds you should make sure that you use all
	four  channels  in  your  structures.  If the music is off, use the
	normal PlaySoundPri() function.  If the music is on, and if it uses
	all  but one of the channels, use this function to re-route all the
	sound effects through the spare channel.

	This function supports prioritisation of sound effects.

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

@{b}SEE ALSO@{ub}
	PlaySoundDACx, PlaySound, PlaySoundPri, @{"games/games.i" LINK "INCLUDES:games/games.i/Main"}

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

@{b}NAME@{ub}	PlaySoundPri -- Play  a sound if it can equal or better a channel's
			priority.

@{b}SYNOPSIS@{ub}
	PlaySoundPri(Sound)
	              a0

	void PlaySoundPri(struct Sound *)

@{b}FUNCTION@{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 SAM_Channel field
	so  that  your  game  makes  maximum use of all the available sound
	channels.

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

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

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

@{b}NAME@{ub}	AllocSoundMem -- Allocate memory for sample playback.

@{b}SYNOPSIS@{ub}
	Memory = AllocSoundMem(Size)
	  d0		       d0

	APTR AllocSoundMem(ULONG Size)

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

@{b}INPUTS@{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}SEE ALSO@{ub}
	FreeMemBlock

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

@{b}NAME@{ub}	GetSound -- Gets the latest version of the sound structure.

@{b}SYNOPSIS@{ub}
	Sound = GetSound()
	  d0

	struct Sound * GetSound(void);

@{b}FUNCTION@{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}SEE ALSO@{ub}
	@{"InitSound" LINK "InitSound()"}

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

@{b}NAME@{ub}	FreeSoundMem -- Frees a block of sound memory.

@{b}SYNOPSIS@{ub}
	FreeSoundMem(MemBlock)
			d0

	void FreeSoundMem(APTR MemBlock);

@{b}FUNCTION@{ub}
	Frees a block of sound memory.

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

@{b}SEE ALSO@{ub}

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

@{b}NAME@{ub}

@{b}SYNOPSIS@{ub}

@{b}FUNCTION@{ub}

@{b}INPUT@{ub}

@{b}RESULT@{ub}

@{b}SEE ALSO@{ub}

@EndNode