Working with PatchDemo

PatchDemo runs on the 3DO development system.

Using PatchDemo involves three basic steps, discussed in more detail in this section:

Refer to Chapter 12 in the 3DO Programmer's Reference for a complete list of DSP instruments.

Creating a patch file

This section first discusses how patch files are used by PatchDemo, then provides a list of available commands.

About patch files

PatchDemo reads commands from a text file describing the patch (the patch file). Each line in a patch file can be a blank line, a comment, or a command. Either UNIX or Mac end of line sequences are acceptable (CR/LF doesn't actually affect the patch, but confuses the line count used for diagnostics). Comments are preceded by a semicolon or pound sign and extend to the end of the line. They may appear on any line. Blank lines are ignored. The example below illustrates the command syntax.

Example 1: Patch file command syntax.

# this is a comment
; so is this
LoadInstrument osc sawtooth.dsp                                            ; everything after the
                                    ; semicolon is a comment
Command lines consist of a command and its arguments, separated by white space (any number of spaces or tabs). Commands are not case-sensitive. Arguments (file names, symbol names, and so on) must not contain white space. Quotes around arguments are not supported.

Commands either create or act on symbols. A symbol is the name of an object created during the patch file processing-for example, a DSP instrument, or a sample. You can connect one instrument to another, adjust an instrument's knob, and so on. There is a separate name space for instruments, samples, and sample attachments, and each symbol must be unique in its name space. Symbols are not case-sensitive. A symbol must have been created before it's used. The example below shows example command lines.

Example 2: Typical command lines.

Tweak osc Amplitude 4000                                                                                ; error; osc not defined yet.
LoadInstrument osc sampler.dsp                                        ; OK
Tweak osc Amplitude 4000                                        ; OK now; osc is now defined.
Note: If an error occurs while reading a patch file, PatchDemo quits after printing an error message containing the line number of the offending line. These errors include unknown commands, missing arguments, duplicate symbol names, undefined symbols, filing errors, lack of memory, and other various system failures.

Patch file commands

The table below provides a quick summary of each command, followed by the page number where you'll find the command described.

Running a patch

To run a patch, issue the following command:

patchdemo.arm <patch file>
<patch file> is the name of a patch description file to load. The patch file is a text file containing the description of the patch. See Creating a patch file.

After a patch file is successfully read, the patch is started (makes a sound) and a page of faders appears on the screen. You can adjust all of the knobs for all of the instruments in the patch except those that have been connected to another instrument. See "Connect" on page for more information. The knobs for each instrument appear on a separate page; there is one page per instrument.

Note: If an instrument has no knobs or all of its knobs are connected to other instruments, PatchDemo will not display a page for the instrument. If all the instruments in a patch do not contain knobs or if all the knobs of al the instruments in a patch are connected to other instruments, PatchDemo will exit with an error message.