Topic : The ATARI Compendium
Author : Scott Sanders / JAY Software
Version : 1.25 (20/6/2003)
Subject : Documentation
Nodes : 1117
Index Size : 32614
HCP-Version : 6
Compiled on : Atari
@charset : UTF-8
@lang : en
@default :
@help : %About
@options : +g -i -t4 +y +z
@width : 100
View Ref-FileWavePlay() XBIOSSyntaxWORD WavePlay( flags, rate, sptr, slen )
WORD flags;
LONG rate;
VOIDP sptr;
LONG slen;
Function WavePlay() provides a easy method for applications to utilize
the DMA sound system on the STe, TT030, and Falcon030 and
playback user-defined event sound effects.
Opcode 165 (0xA5)
Availability Available only when the 'SAM\0' cookie exists.
Parameters flags is a bit mask consisting of the following options:
Name Mask Meaning
WP_MONO 0x00 The sound to be played back is
monophonic.
WP_STEREO 0x01 The sound to be played back is in
stereo.
WP_8BIT 0x00 The sound to be played back was sampled
at 8-bit resolution.
WP_16BIT 0x02 The sound to be played back was sampled
at 16-bit resolution.
WP_MACRO 0x100 Play back a user-assigned macro or
application global sound effect. This
flag is exclusive and modifies the
meaning of the other parameters to this
call as shown below.
rate specifies the sample rate in Hertz (for example 49170L
to play back at 49170 Hz). If WP_MACRO was specified in
flags, then this parameter is ignored and should be set to
0L. sptr is a pointer to the sound sample in memory. If
WP_MACRO was specified in flags then this parameter should be
a LONG containing either the application cookie specified in
the .SAA file or the 'SAM\0' cookie to play an application
global. slen is the length of the sample in bytes.
If WP_MACRO was specified in flags then slen is the macro or
application global index as specified in the .SAA file.
Valid application global values are as follows:
Name slen Usage
AG_FIND 0 Call WavePlay() with this value when the
user requests display of the 'Find' dialog
box.
AG_REPLACE 1 Call WavePlay() with this value when the
user requests display of the 'Replace'
dialog box.
AG_CUT 2 Call WavePlay() with this value when the
user requests a 'Cut' operation.
AG_COPY 3 Call WavePlay() with this value when the
user requests a 'Copy' operation.
AG_PASTE 4 Call WavePlay() with this value when the
user requests a 'Paste' operation.
AG_DELETE 5 Call WavePlay() with this value when the
user requests a 'Delete' operation. This
should not be called when the user presses
the 'Delete' key.
AG_HELP 6 Call WavePlay() with this value when the
user requests display of application
'Help.' This should not be called when the
user presses the 'Help' key.
AG_PRINT 7 Call WavePlay() with this value when the
user requests display of the 'Print'
dialog box.
AG_SAVE 8 Call WavePlay() with this value when the
user requests that the current document be
saved. This should not be used for any
operation that calls the file selector.
AG_ERROR 9 Call WavePlay() with this value when the
application encounters an error not
presented to the user in an alert or error
dialog (error dialogs may be assigned
sounds).
AG_QUIT 10 Call WavePlay() with this value when the
user requests that the application exit.
Use this global after the user has
confirmed a quit with any dialog box that
may have been necessary.
Binding move.l slen,-(sp)
pea sptr
move.l rate,-(sp)
move.w flags,-(sp)
move.w #$A5,-(sp)
trap #14
lea 16(sp),sp
Return Value WavePlay() returns WP_OK (0) if the call was successful,
WP_ERROR (-1) if an error occurred, or WP_NOSOUND (1) to
indicate that no sound was played (either because the user
had not previously assigned a sound to the given macro or SAM
was disabled).
Caveats This function is only available when the System Audio Manager
TSRTermitate and Stay Resident programm
(available from Atari Corp. or SDS) is installed.
Extended development information is available online the
Atari Developer's roundtable on GEnie. Because of previously
misdocumented sample rates, the value for rate must be 33880
to play back a sample at 32880 Hz, 20770 to play back
a sample at 19668 Hz, and 16490 to play back a sample at
16390 Hz.
Comments Even if an application does not install any custom events in
a .SAA file, an application must still provide a .SAA file if
it wishes to use application globals so that the SAM
configuration accessory allows the user to assign those
sounds. A macro is commonly used to access the application
global sounds available as follows:
#define WavePlayMacro(a) WavePlay( WP_MACRO, 0L, SAM_COOKIE, a );