Specifications

SERIES 3/3A PROGRAMMING GUIDE
3-2
The way to check the device driver is loaded is to make the call
p_loadldd("SNDFRC.LDD");
where the full path of the
.ldd
file can be given. (The
.ldd
file has to be copied onto the Series 3.)
The return values zero and
E_FILE_EXIST
can both happily be ignored. Other errors are more serious -
they probably mean that the file
sndfrc.ldd
cannot be located. In this case, the program cannot continue (at
least, not as according to its original intention).
Opening a channel to MUS:
Another pre-requisite to using the services of
sndfrc.ldd
is to open a channel to
MUS:
. This is done in the
standard manner for all i/o devices:
p_open(&handle,"MUS:",-1);
If this call is successful, it writes back the handle of the channel established to the device driver. All
subsequent requests from the program (until such time as the channel is closed) should be made via this
handle.
Possible errors from the
p_open
call include:
•
"invalid arguments" - which probably means
sndfrc.ldd
has not been installed (or, having once
been installed, it has since been de-installed)
•
"in use" or "locked" - another application is currently making use of the loudspeaker.
In the second of these two cases, a brief retry philosophy might be adopted. If the channel still cannot be
opened, a suitable error message should be displayed - leaving it up to the user to retry at some later time.
Actually creating sounds
The way sounds are actually caused to be emitted is by using the
P_FWRITE
service of the
MUS:
channel.
As for all device drivers, the
P_FWRITE
request can be made synchronously (eg using the utility function
p_write
) or, for more quality applications, asynchronously. If the request is made asynchronously, it
allows the use of the
P_FCANCEL
service to interrupt and terminate a sequence of notes as they are playing.
For example,
p_ioc5(handle,P_FWRITE,&musstat,&buf[0],&len);
to play a buffer of notes asynchronously.
The parameter
len
(passed by reference) gives the number of notes in the buffer. The maximum allowed
value of
len
is 500. (For arbitrarily long sequences of notes, call the
P_FWRITE
service more than once.)
Each note is specified by one
UWORD
in the buffer - so that
buf
would be declared as
UWORD buf[ ]
For each note, the
UWORD
contains three pieces of information:
tone
,
length
, and
loudness
.
There are only four possible values of loudness:
0
(the quietest),
1
,
2
, and
3
(the loudest). The loudness is
multiplied by
64
before being added into the
UWORD
for the note.
The duration is measured in 1/100ths of a second, and can have any value from
1
to
255
. The duration is
multiplied by
256
before being added into the
UWORD
for the note.
The allowed values of tone range in principle from
0
to
0x3f
. See below for more details.