Appendix 1: The MIDI Interface

This appendix contains documentation for calls in the module midifns.c. Type boolean is an int that takes on values of true or false, and type byte is an unsigned char. Channels are numbered from 1 to 16, control numbers are from 0 to 127, and program numbers are from 1 to 128. This corresponds to the MIDI standard for ``external'' numbers, in other words what users should see on front panels and computer displays. The actual hardware representation for channels and program numbers is usually based at zero, and midifns.c provides this conversion.

void alloff(void)

This procedure sends a MIDI all notes off message to all channels.

void eventwait(long timeout)

Wait until either input arrives or timeout. If 1 is specified, wait only for input. In Unix, Mach, and Amiga implementations, eventwait suspends the current process.

void exclusive(boolean onflag)

This procedure tells the MPU-401 to read exclusive messages into the buffer provided by a previous call to midi buffer. Onflag is set to true to receive MIDI exclusive data, otherwise it is set to false.

boolean getbuf(boolean waitflag, byte *p)

getbuf copies 4 bytes of data from the MIDI input buffer to *p. The fourth byte in the Amiga implementation is the port number of the message sender. It will wait initially for buffer to become nonempty if and only if waitflag is true. It returns true if data was written to *p, and false if data was not written to *p. Only the first 3 bytes of system exclusive messages are available via getbuf. When a system exclusive message is received here, call get_excl() to get the whole message. After receiving the first 3 bytes of a system exclusive message, a subsequent call to getbuf (without intervening calls to get_excl) will delete the system exclusive message.

long get_excl(char *buffer, long len)

get_excl copies len bytes of a system exclusive message to buffer. If the message is shorter than len, only one message is copied. If the message is longer than len, only the first len bytes are copied, and the next call to get_excl will start where the previous call left off. In all cases, the number of bytes copied is returned. Zero indicated no messages are present. To avoid polling two message queues, the first 3 bytes of every system exclusive message are delivered as a normal MIDI message (returned by calls to getbuf) in addition to being placed in the system exclusive message queue. Thus, when a system exclusive message is received via getbuf, you should call get_excl to get the entire message. Note that buffer will get the entire message, including the first 3 bytes.

int getkey(boolean waitflag)

getkey tries to read a key. It returns the key number of the key which has been depressed, or the key number plus 128 of a key which has been released. It returns 1 if waitflag is false and no key has been pressed. If waitflag is true this routine will block until a key is pressed. Since getkey uses getbuf (see above), non-key events (e.g. pitch bend) will be read and discarded by getkey.

long gettime()

Return the time in 1000ths of seconds since the last call to musicinit or timereset.

void l_restrest(long time)

l_rest waits until the amount of time specified by time has elapsed.

Previous Section | Next Section | Table of Contents | Index | Title Page