Paul Jones and PJCO present...
 __      __                            ____    ___                         
/\ \  __/\ \                          /\  _`\ /\_ \                        
\ \ \/\ \ \ \     __     __  __     __\ \ \L\ \//\ \      __     __  __    
 \ \ \ \ \ \ \  /'__`\  /\ \/\ \  /'__`\ \ ,__/ \ \ \   /'__`\  /\ \/\ \   
  \ \ \_/ \_\ \/\ \L\.\_\ \ \_/ |/\  __/\ \ \/   \_\ \_/\ \L\.\_\ \ \_\ \  
   \ `\___x___/\ \__/.\_\\ \___/ \ \____\\ \_\   /\____\ \__/.\_\\/`____ \ 
    '\/__//__/  \/__/\/_/ \/__/   \/____/ \/_/   \/____/\/__/\/_/ `/___/> \
                                                                     /\___/
                                                                     \/__/ 

            Use System Audio Manager (SAM) with HiSoft BASIC...
              
Disclaimer
---------------------------------------------------------------------------

PJCO and Paul Jones cannot be responsible for any damage caused to you 
or your computer when using WavePlay lib.

What is it?
---------------------------------------------------------------------------

WavePlay is library for HiSoft BASIC which will let you use SAM. With 
SAM and KP SACK you can create SAM Aware Applications (SAA) files 
which let your program have sounds to certain events.

Installation
--------------------------------------------------------------------------

1) First you need to update your libraries. To do this find your LIB 
   folder (which contains your library .BIN files), copy WAVEPLAY.BIN 
   there and double click on BUILDLIB.TTP. For parameters, enter 
   "WAVEPLAY -q" and press [return]. The program will now make a file 
   called HBASIC.LIB.
   
2) Copy the new HBASIC.LIB file to the same directory as your HBASIC 
   editor.

3) Copy WAVEPLAY.BH to your include folder.

Commands
---------------------------------------------------------------------------

FUNCTION WavePlay% (flags%,rate&,sound&,length&)

This plays a sample at the given rates, with given properties.

FLAGS:

WP_STEREO   0x00 - stereo
WP_MONO     0x01 - mono

WP_8BIT     0x00 - 8bit
WP_16BIT    0x02 - 16bit

WP_NOUSEDSP 0x00 - don't use the DSP (with AFM)
WP_USEDSP   0x04 - use the DSP (with AFM)

RATE& is the speed of playback:

ACT_CLK50K  49170   TT_CLK50K  50066
ACT_CLK33K  33880   TT_CLK25K  25033
ACT_CLK25K  24585   TT_CLK12K  12517
ACT_CLK20K  20770   TT_CLK6K    6258
ACT_CLK16K  16490
ACT_CLK12K  12292
ACT_CLK10K   9834
ACT_CLK8K    8195

SOUND& is the pointer to the start of the sample. LENGTH is the length 
in bytes.

Returns: 0 if sample played, -1 if not played (bad parameter)

FUNCTION WavePlayMacro% (cookie&, global&)

COOKIE& is the value of the cookie to play. GLOBAL& is the global 
value to play in it.

Returns: 0 if sound played, 1 if SAA not installed

FUNCTION WavePlayGlobal% (global&)

Plays a global sound.

Returns: 0 if sound played, 1 if not.

AP_MACRO.H
---------------------------------------------------------------------------

At the moment SACK only outputs include files in C format. You can use 
CTOBAS.TTP to do the most work, but more is needed:

'
' Lattice C header file for E:\HBASIC\PJCO\NETCHAT.SAA.
'
' Automatically generated by KP SACK at 17:13 on 18/8/1997
' For more info, go to: 
'                http://www.cs.man.ac.uk/~jacquesa/kpp/


' SAA cookie.
CONST SAA_COOKIE&=&H4e434854

<the above MUST have a "&" symbol. Also, 0x??? represents a hexdecimal 
 number in C, so add &H to the beginning of the value>

' Application Macros
CONST SAA_YOU_HAVE_X_MESSAGES%=0
CONST SAA_YOU_HAVE_0_MESSAGES%=1


You must include the file. In your program, you can something like:

sam_present=GETCOOKIE ("SAM"+CHR$(0),junk&)
IF sam_present THEN
	junk=waveplayglobal (0)
' this will play the global sound of start program (KP global)
	junk=WavePlayMacro (saa_cookie&,saa_you_have_x_messages)
' plays the sound set to the "you have x messages" event.
END IF

Legal
---------------------------------------------------------------------------

WavePlay is freeware, which means that no money should be payed for 
using this software. Any programs which use the extension should have 
the library named in the docs/program.

Please feel free to give me ANY comments about the library as I would 
like to know what improvements/adjustments could be made. 

Contact
---------------------------------------------------------------------------

I (Paul Jones) am contactable from my email address 
"paulat.jones@zetnet.co.uk". I also have a homepage at 
"http://www.users.zetnet.co.uk/pjones/home.htm".