home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
DP Tool Club 26
/
CD_ASCQ_26_1295.iso
/
vrac
/
gctv101.zip
/
GOLDSAPI.DOC
< prev
next >
Wrap
Text File
|
1995-09-18
|
12KB
|
246 lines
______________________________________________________________________
The Goldware Sound API
Version 1.00, August 9th, 1995
A specification written by Odinn Sorensen
Donated to the Public Domain
______________________________________________________________________
The Goldware Sound API (GSAPI) is a set of functions provided by an
interrupt service function installed on the Alternate Multiplex
Interrupt (AMI) 2Dh. For full details on the Alternate Multiplex
Interrupt, please see Ralf Brown's Interrupt List (INTER46*.ZIP), his
AMI specification (ALTMPX35.ZIP) and/or his AMIS library
(AMISL091.ZIP).
This chapter contains a specification of the current of the GSAPI.
Refer to the AMI specification for details about implementing an AMI
interrupt service function.
In the AMI specification there is an installation check function which
returns a signature string which identifies installed interrupt
services. The signature string for the GSAPI is as follows:
Manufacturer's name: Goldware
Product name: GoldSAPI
Signature as it would appear in Ralf Brown's Interrupt List:
'Goldware' 'GoldSAPI' The Goldware Sound API by Odinn Sorensen.
Applications looking for the GSAPI should scan the AMI for signatures
and if it finds a match (not case sensitive) on the product name plus
a version from 1.00 up to 1.99, it can consider the GSAPI installed
and ready. A major version different from 1 must be considered totally
incompatible with version 1.xx. All version 1.xx's must be backward
compatible.
Note that the manufacturer's name does not have to be "Goldware". This
is to allow you to brand your own GSAPI implementations with your own
manufacturer's name in the signature.
Here is the specification as it would appear in Ralf Brown's Interrupt
List:
--------s-2D--10-----------------------------
INT 2D - Goldware Sound API (GSAPI) - OPEN API
AL = 10h
AH = AMIS multiplex number for the Goldware Sound API.
Return: AX = 0000h if successful, 0001h if another caller has already
opened the api, FFFFh if the api is cannot be opened
for any other reason.
BX = A unique key value which the caller must use again when
closing the api using the AL=11h function.
CX = The size of the gsapidata structure.
DX:DI -> Pointer to the gsapi structure (see below).
Program: The Goldware Sound API (GSAPI) is a generic sound driver API
designed by Odinn Sorensen of Goldware International. The
GSAPI was originally invented for sound card support in the
GoldED mail reader.
Note: This function must be called before any other function. It is
a hint to the api that it must get ready to load and play
sounds. Depending on the implementation, this function may
not do anything except prevent other access until the AL=11h
close api function is called.
The unique key value can be anything, but it is suggested to
simply keep a count of the number of calls to this function
and use that as the key value.
Format of the gsapidata structure:
Offset Size Description
00h WORD Version of the sound driver (*).
02h WORD Version of the dsp (*).
04h WORD I/O port number (*).
06h BYTE IRQ number (*).
07h BYTE DMA channel number (*).
08h WORD Current sample rate in Hz (*).
0Ah WORD Status word. FFFFh if a sound is playing.
0Ch WORD Segment of requested memory buffer.
0Eh WORD Offset of requested memory buffer.
10h DWORD Length of requested memory buffer.
14h 80 ASCIIZ parameters string.
Note: The gsapidata structure members marked with (*) are
informational (read) only for caller programs and may or may
not be set to real values by the api. Any data which the api
cannot determine is set to zero.
--------s-2D--11-----------------------------
INT 2D - Goldware Sound API (GSAPI) - CLOSE API
AL = 11h
AH = AMIS multiplex number for the Goldware Sound API.
BX = The unique key value which was returned by the AL=11h
open api function.
Return: AX = 0000h if successful, 0001h if the api was not open, FFFFh
if the key value was not correct.
Note: This function will automatically call the AL=15h stop sound
and AL=13h close sound file functions if necessary.
--------s-2D--12------------------------------
INT 2D - Goldware Sound API (GSAPI) - OPEN AND LOAD SOUND FILE
AL = 12h
AH = AMIS multiplex number for the Goldware Sound API.
The name of the sound file is given in the gsapidata
parameters string field.
If the gsapidata length field is non-zero, the segment and
offset fields are assumed to be a pointer to a buffer which
can be used to load the file.
Return: AX = error code
0000h - Sound file was opened and loaded without errors
0001h - A sound file was already opened and must be closed
first.
0002h - A memory buffer is needed to load the file. The api
sets the gsapidata length field to the amount of
memory needed. The calling program must allocate
the memory buffer, set the segment and offset
fields in the gsapidata structure and then call
this function again. The file is not considered
open until the file has been successfully loaded.
Depending on the implementation, the memory buffer
requested may be as large as the entire file, even
longer than 64K.
0003h - Sound file format not supported.
FFFFh - DOS returned an error when accessing the file. BX
contains the DOS error code.
Note: This function may optionally set the gsapidata sample rate
field to the primary sample rate as found in the sound file.
The sample rate field must be set to zero if setting of the
sample rate is not supported.
The function is allowed to close the file immediately after
loading, but then it must "pretend" that it is open so that
the AL=13h close sound file function will succeed.
The sound file is only loaded, not played.
--------s-2D--13-----------------------------
INT 2D - Goldware Sound API (GSAPI) - CLOSE SOUND FILE
AL = 13h
AH = AMIS multiplex number for the Goldware Sound API.
Return: AX = 0000h if successful, 0001h if no sound file is open.
Note: The calling program must call this function before
deallocating the memory buffer if it was allocated.
--------s-2D--14-----------------------------
INT 2D - Goldware Sound API (GSAPI) - PLAY SOUND
AL = 14h
AH = AMIS multiplex number for the Goldware Sound API.
BX = Sample rate in Hz or zero to use default sample rate.
Return: AX = 0000h if successful, 0001h if there is no sound to play.
Note: Plays the sound file which was previously loaded using the
AL=12h load sound function. The sound is played from the
beginning. If a sound is already playing, it is restarted.
Sounds are assumed to be played in the background and this
function will return as soon as playback is started.
Implementation of the sample rate setting is optional. If it
is implemented and the sample rate is valid, it will be
copied to the gsapidata sample rate field.
--------s-2D--15-----------------------------
INT 2D - Goldware Sound API (GSAPI) - STOP SOUND
AL = 15h
AH = AMIS multiplex number for the Goldware Sound API.
Return: AX = 0000h if successful, 0001h if there is no sound to stop.
Note: If a sound is playing, it is stopped.
--------s-2D--16-----------------------------
INT 2D - Goldware Sound API (GSAPI) - PAUSE SOUND
AL = 16h
AH = AMIS multiplex number for the Goldware Sound API.
Return: AX = 0000h if successful, 0001h if there is no sound to pause.
Note: If a sound is playing, it is temporarily paused. Playback can
be resumed by calling the AL=16h resume sound function.
--------s-2D--17-----------------------------
INT 2D - Goldware Sound API (GSAPI) - RESUME SOUND
AL = 17h
AH = AMIS multiplex number for the Goldware Sound API.
Return: AX = 0000h if successful, 0001h if there is no sound to
resume.
Note: If a sound is paused using the AL=16h pause sound function,
playback is resumed from the point it was paused.
--------s-2D--18-----------------------------
INT 2D - Goldware Sound API (GSAPI) - BREAK SOUND LOOP
AL = 18h
AH = AMIS multiplex number for the Goldware Sound API.
BX = 0001h to break looping sample immediately, 0000h to break
loop after looping sample has played to the end.
Return: AX = 0000h if successful, 0001h if there is no sound to break,
FFFFh if the function is not supported.
Note: Implementation of this function is optional, but if it is
implemented, it must not simply stop playing a sound, unless
the currently looping sample was the last.
Calling programs may want to call this function to determine
if loop breaking is possible and if not, use a different
method for breaking loops, for example by allowing users to
press a key to stop a playing sound.
--------s-2D--19-----------------------------
INT 2D - Goldware Sound API (GSAPI) - SPEAKER ON/OFF
AL = 19h
AH = AMIS multiplex number for the Goldware Sound API.
BX = 0000h to turn off the speaker, 0001h to turn it on.
Return: Nothing.
Note: The speaker is assumed to already be on when the api is
opened.
---------------------------------------------
I have implemented a program loader which provides the interrupt
service function with the Goldware Sound API. The current version of
the program loader is named GCTVSAPI 1.00 and may be found in the
archive GCTV100.ZIP. The current version of GCTVSAPI loads the
Creative Labs CT-VOICE.DRV file for playing of .VOC files on Sound
Blasters or 100% compatibles.
I hope that others will write program loaders or TSR's that implement
the Goldware Sound API for other sound cards than the Sound Blasters,
or even a Sound Blaster compatible implementation that does not
require CT-VOICE.DRV.
If you have written a Goldware Sound API implementation, please let me
know, so that I and the reg.sites can make it available for other
users.
Enjoy!
Odinn Sorensen
______________________________________________________________________
Author contact information
______________________________________________________________________
Goldware International
Odinn Sorensen
Boeslunde Byvej 114
DK-4242 Boeslunde
Denmark, Europe
Voice phone: +45-53540015
Fax: +45-58162222
Data, ModemV34: +45-58162222
Data, EuroISDN: +45-58162223
Internet: odinn@ibm.net
odinn@winboss.dk
FidoNet: 2:236/77.0 (ModemV34)
2:236/1077.0 (EuroISDN)
______________________________________________________________________