\documentclass[10pt,letterpaper,onecolumn]{book}
\usepackage{comment}
\usepackage{vmargin}
\usepackage{t1enc}
\usepackage{fancyvrb}
\usepackage{url}
\usepackage{calc}
\usepackage{array}
\usepackage{fancyhdr}
\usepackage{graphicx}
\usepackage{color}
\usepackage{listings}
\usepackage[latin1]{inputenc}
\usepackage[english]{babel}
\usepackage{doc/latex/doxygen}
\pagestyle{headings}
\begin{document}
\definecolor{LstColor}{cmyk}{0.1,0.1,0,0.05} 
\lstset{language=c++,basicstyle=\ttfamily\scriptsize,commentstyle=\ttfamily\scriptsize,tabsize=2,breaklines,backgroundcolor=\color{LstColor},fontadjust=true,fancyvrb=true,moredelim=[is][\textbf]{\\emph\{}{\}}}.

\title{Csound and CsoundVST}
\author{Michael Gogins \\ \texttt{gogins@pipeline.com}}
\maketitle

%\abstract{This document explains how to download, install, use, build, and extend Csound and CsoundVST on Windows and Linux.}

\section{Introduction}

Csound is a unit-generator based, user-programmable computer music system. It was originally written by Barry Vercoe at the Massachusetts Institute of Technology in 1984 as the first C language version of this type of software. Since then Csound has received numerous contributions from researchers, programmers, and musicians around the world. 

Around 1991, John ffitch ported Csound to Microsoft DOS. Csound currently runs on many varieties of UNIX and Linux, Microsoft DOS and Windows, all versions of the Macintosh operating system including Mac OS X, and others.

Csound is maintained by John ffitch at \url{http://www.sourceforge.net/projects/csound}. Documentation for the Csound language is maintained by Kevin Conder at \url{http://kevindumpscore.com/}. Csound's ``home page'' is maintained by Richard Boulanger at \url{http://csounds.com}. 

There are newer computer music systems that have graphical patch editors (e.g. Max/MSP, PD, jMax, or Open Sound World), or that use more advanced techniques of software engineering (e.g. Nyquist or SuperCollider). But Csound still has the largest and most varied set of unit generators, is the best documented, runs on the most platforms, and is the easiest to extend. It is possible to compile Csound using double-precision arithmetic throughout for superior sound quality. In short, Csound must be considered one of the most powerful musical instruments ever created.

Csound development is ongoing, and currently stands at version 5 beta. New features in Csound 5 include the GNU Lesser General Public License, plugin unit generators, an application programming interface (API) for embedding Csound in other software, and the use of widely accepted third-party libraries for cross-platform development: \texttt{libsndfile} for reading and writing soundfiles, PortAudio for reading and writing digital audio from sound cards, and the Fast Light Tool Kit (FLTK) for graphics.

To create music with Csound:

\begin{enumerate}
\item Write an orchestra (\texttt{.orc} file) that creates instruments and signal processors by connecting unit generators (also called opcodes, in Csound-speak) using Csound's simple programming language.
\item Write a score (\url{.sco} file) that specifies a list of notes and other events to be rendered by the orchestra.
\item Run Csound to compile the orchestra and score, run the sorted and preprocessed score through the orchestra, and write digital audio out to a soundfile or sound card.
\end{enumerate}

CsoundVST is an extended version of Csound that adds a graphical user interface, C++ and Python APIs, Python scripting, a library of Python extension modules for algorithmic composition, a VST plugin interface, and a \emph{Mathematica} interface.

In addition to this ``canonical'' version of Csound and CsoundVST, there are other versions of Csound and other front ends for Csound, many of which can be found at \url{http://csounds.com}.

\section{Downloading}

Csound is hosted at \url{http://www.sourceforge.net/projects/csound}. \linebreak Source and binary packages are available from the \texttt{files} link off that page.

\section{Installing}

Once you have either unpacked a binary distribution, or built Csound from sources, you will need to install and configure Csound so that it will run properly on your system. 

\subsection{Csound}

Consult the Csound language documentation for instructions on how to install and configure Csound.

On Windows, make sure the directory or directories (normally the \texttt{csound5} directory) containing the Csound executables directory and all the Csound plugin opcodes are also in your \texttt{PATH} variable, or else copy all the executable files to your Windows \texttt{system32} directory.

On Unix and Linux, either install the Csound program in one of the system bin directories, typically \texttt{/usr/local/bin}, and the Csound and plugin shared libraries in one of the system lib directories, typically \url{/usr/local/lib}; or make sure that the directory containing the Csound and plugin shared libraries is in your \texttt{LD\_LIBRARY\_PATH} environment variable. This variable may have a different name in different operating systems.

\subsection{CsoundVST}

CsoundVST requires some additional configuration. On all platforms, CsoundVST requires that you have Python installed on your computer. The directory containing the \texttt{\_CsoundVST} shared library and the \texttt{CsoundVST.py} file must be in your \texttt{PYTHONPATH} environment variable, so that the Python runtime knows how to load these files.

\section{Using}

Assuming that you have installed and configured the software, Csound and CsoundVST can be operated in a variety of modes and configurations. The \texttt{.csd} and \texttt{.py} files in the \texttt{examples} demonstrate a few of these modes of operation. Some of these scores are simple, others are moderately complex. 

You may need to edit the \texttt{----opcode-lib} option in the Csound command in some of the  \texttt{.csd} and \texttt{.py} files to match your environment. Similarly, you may need to edit the SoundFont file paths in instrument definitions that use the \texttt{fluid} SoundFont 2 player opcode to match your environment.

\subsection{Real-Time Audio}

For real-time audio output, with or without MIDI control, you will probably want to tune the \texttt{kr} and \texttt{ksmps} orchestra statements, and the \texttt{-b} and \texttt{-B} command-line options, to give you the shortest possible latency that does not cause clicks or stutters in Csound's audio output. 

\subsubsection{Windows with ASIO}

On Windows, Csound is configured with the ASIO build of the PortAudio library. At this time, it is necessary to set both the \texttt{-B} and the \texttt{-b} command-line options to have the same value as the \texttt{ksmps} variable set in the orchestra file. For example, \texttt{sr = 44100}, \texttt{kr = 100}, \texttt{ksmps = 441}, \texttt{-b441} and \texttt{-B441} give a CD-equivalent audio sampling rate of 44,100 frames per second, a control sampling rate of 100 control samples per second with 441 audio sample frames per control sample, an audio output software buffer size of 441 sample frames, and an audio output device hardware buffer size of 441 sample frames, which yields an audio output latency of 10 milliseconds --- quite fast enough for reasonably expressive keyboard playing or other real-time instrumental performance. Even lower latencies are possible with smaller values of \texttt{-B}, \texttt{-b}, and \texttt{ksmps}, down to less than a millisecond on Windows XP.

If your sound card does not have an ASIO driver, you can still use Csound with ASIO by downloading and installing the \texttt{asio4all} adapter from \url{http://michael.tippach.bei.t-online.de/asio4all}.

\subsubsection{Linux with ALSA}

On Linux with ALSA, the audio output device should be selected using a special form of the \texttt{-odac} option, for example \texttt{-odac:plughw:0} for device 0. The \texttt{plughw} option translates Csound's audio output to the format expected by the sound card. With ALSA, latencies of a few milliseconds are possible, and expressive real-time instrumental performance should be quite feasible.

\subsection{Csound}

\subsubsection{The \texttt{csound} Command}

The original method for running Csound was as a console program. This, of course, still works. Running \texttt{csound} without any arguments prints out a list of command-line options, which are more fully explained in the Csound language documentation. Normally, the user executes something like \texttt{csound -W -omysoundfile myorchestra.orc myscore.sco} or, to use the single-file Csound structured data (\texttt{.csd}) format, \texttt{csound myscore.csd}.

Csound can read and write soundfiles (off-line rendering), read and write digital audio using a sound card (real-time rendering), read and write MIDI files, and read and write MIDI using a MIDI interface and controller (real-time control). See the Csound language documentation for more details. 

\subsubsection{The Csound API}

The Csound API consists of the Csound library (\texttt{libcsound.a}) and the Csound header file (\texttt{csound.h}). You can build Csound into your own software very easily using this API. For example, the Csound command itself is made this way:

\begin{lstlisting}
#include "csound.h"

int main(int argc, char **argv)
{
    // Create Csound.
    void *csound = csoundCreate(0);
    // One complete performance cycle.
    int result = csoundCompile(csound, argc, argv);
    if(!result)
    {
        while(csoundPerformKsmps(csound) == 0){}
        csoundCleanup(csound);
    }
    // Destroy Csound.
    csoundDestroy(csound);
    return result;
}
\end{lstlisting}

%\include{doc/latex/classCppSound}
%\include{doc/latex/classCsoundFile}

\subsection{CsoundVST}

CsoundVST is a multi-function front end for Csound, based on the Csound API. CsoundVST runs as a stand-alone graphical user interface to Csound, or as a VST plugin in hosts such as the Cubase audio sequencer. CsoundVST provides both a C++ and a Python API to Csound, and to a set of classes for algorithmic composition. 

CsoundVST contains a built-in Python interpreter. With Python, the user can generate a score, import a MIDI file, process notes, load and run a Csound orchestra, and in general do anything that can be done either with Csound or in Python.

\subsubsection{Standalone}

To run CsoundVST as a stand-alone front end to Csound, execute \texttt{CsoundVST}. When the program has loaded, you will see a graphical user interface with a row of buttons along the top. Click on the \emph{Open...} button to load a \texttt{.csd} file. You can also click on the \emph{Open...} button and load a \texttt{.orc} file, then click on the \emph{Import...} button to add a \texttt{.sco} file. You can edit the Csound command, the orchestra file, or the score file in the respective tabs of the user interface. When all is satisfactory, click on the \emph{Perform} button to run Csound. You can stop a performance at any time by clicking on the \emph{Stop} button.

\subsubsection{The CsoundVST API}

CsoundVST extends the Csound API with C++. There is a C++ class for the Csound API proper, another C++ class for manipulating Csound files in code, and additional classes for algorithmic composition based on music space. All these C++ classes also have a Python interface in the \texttt{CsoundVST} Python extension module. For more information, consult the Doxygen-generated files in the \url{csound5/doc} directory.

You can build CsoundVST into your own software using the \texttt{\_CsoundVST} shared library and \texttt{CsoundVST.hpp} header file. For example, the CsoundVST stand-alone graphical user interface program is made this way:

\begin{lstlisting}
#include <CsoundVST.hpp>
#include <CsoundVstFltk.hpp>

int main(int argc, char **argv)
{
    CsoundVST *csoundVST = CreateCsoundVST();
    AEffEditor *editor = csoundVST->getEditor();
    editor ->open(0);
    return 0;
}
\end{lstlisting}

There is also a high-level C API for CsoundVST, declared in \url{frontends/CsoundVST/csoundvst\_api.h}. Any program able to interface with C calling convention functions can use this API. For example, a \textbf{\emph{Mathematica}} 5.0 notebook can use the .NET/Link package's \texttt{DefineDLLFunction} to access the CsoundVST API to create an instance of CsoundVST, load an orchestra, generate a score using the power of \textbf{\emph{Mathematica}}, and render that score.

\subsubsection{Python scripting}

You can use CsoundVST as a Python extension module. In fact, you can do this either in a standard Python interpreter, such as Python command line or the Idle Python GUI, or in CsoundVST itself in Python mode.

To use CsoundVST in a standard Python interpreter, import CsoundVST.

\begin{lstlisting}
import CsoundVST
\end{lstlisting}

The CsoundVST module automatically creates an instance of CppSound named \texttt{csound}, which provides an object-oriented interface to the Csound API. In a standard Python interpreter, you can load a Csound \texttt{.csd} file and perform it like this: 

\begin{lstlisting}
C:\Documents and Settings\mkg>python
Python 2.3.3 (#51, Dec 18 2003, 20:22:39) [MSC v.1200 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import CsoundVST
>>> csound.load("c:/projects/csound5/examples/trapped.csd")
1
>>> csound.exportForPerformance()
1
>>> csound.perform()
BEGAN CppSound::perform(5, 988ee0)...
BEGAN CppSound::compile(5, 988ee0)...
Using default language
0dBFS level = 32767.0
Csound version 5.00 beta (float samples) Jun  7 2004
libsndfile-1.0.10pre6
orchname:  temp.orc
scorename: temp.sco
orch compiler:
398 lines read
        instr   1
        instr   2
        instr   3
        instr   4
        instr   5
        instr   6
        instr   7
        instr   8
        instr   9
        instr   10
        instr   11
        instr   12
        instr   13
        instr   98
        instr   99
sorting score ...
        ... done
Csound version 5.00 beta (float samples) Jun  6 2004
displays suppressed
0dBFS level = 32767.0
orch now loaded
audio buffered in 16384 sample-frame blocks
SFDIR undefined.  using current directory
writing 131072-byte blks of shorts to test.wav
 WAV
SECTION 1:
ENDED CppSound::compile.
ftable 1:
ftable 2:
ftable 3:
ftable 4:
ftable 5:
ftable 6:
ftable 7:
ftable 8:
ftable 9:
ftable 10:
ftable 11:
ftable 12:
ftable 13:
ftable 14:
ftable 15:
ftable 16:
ftable 17:
ftable 18:
ftable 19:
ftable 20:
ftable 21:
ftable 22:
new alloc for instr 1:
B  0.000 ..  1.000 T  1.000 TT  1.000 M:     32.7      0.0
new alloc for instr 1:
B  1.000 ..  3.600 T  3.600 TT  3.600 M:    207.6      0.1

...

B 93.940 .. 94.418 T 98.799 TT281.799 M:    477.6     85.0
B 94.418 ..100.000 T107.172 TT290.172 M:    118.9     11.5
end of section 4         sect peak amps:  25950.8  26877.4
inactive allocs returned to freespace
end of score.              overall amps:  32204.8  31469.6
           overall samples out of range:        0        0
0 errors in performance
782 131072-byte soundblks of shorts written to test.wav WAV
Elapsed time = 13.469000 seconds.
ENDED CppSound::perform.
1
>>>
\end{lstlisting}

To use CsoundVST itself as your Python interpreter, click on the CsoundVST Settings tab, and select the Python check box in the Csound performance mode box. Do not create a new CppSound object; you must use the builtin \texttt{csound} object in the CsoundVST module. 

The \texttt{koch.py} script shows how to use Python to do algorithmic composition for Csound. You can use Python triple-quoted string literals to hold your Csound files right in your script, and assign them to Csound: 

\begin{lstlisting}
csound.setOrchestra('''sr = 44100
kr = 441
ksmps = 100   
nchnls = 2
0dbfs = .1
instr 1,2,3,4,5 ; FluidSynth General MID
I; INITIALIZATION
; Channel, bank, and program determine the preset, that is, the actual sound.
ichannel		=			p1
iprogram		=			p6
ikey	 		= 			p4
ivelocity 		= 			p5 + 12
ijunk6 			= 			p6
ijunk7			=			p7
; AUDIO
istatus			=			144;			
print			iprogram, istatus, ichannel, ikey, ivelocityaleft, aright		
fluid			"c:/projects/csound5/samples/VintageDreamsWaves-v2.sf2", \\
    iprogram, istatus, ichannel, ikey, ivelocity, 1			
outs 			aleft, arightendin''')
csound.setCommand("csound --opcode-lib=c:/projects/csound5/fluid.dll \\
    -RWdfo ./koch.wav ./temp.orc ./temp.sco")
csound.exportForPerformance()
csound.perform()
\end{lstlisting}

To run your script in Csound VST, click on the Perform button. 

\subsubsection{VST Plugin}
The following instructions are for Cubase SX. You would follow roughly similar procedures in other hosts.

Use the \emph{Devices} menu, \emph{Plug-In Information} dialog, \emph{VST Plug-Ins} tab, \emph{Shared VST Plug-ins Folder} text field to add your \texttt{csound5} directory to Cubase's plugin path. You can have multiple directories separated by semicolons. 

Quit Cubase, and start it again. 

Use the \emph{File} menu, \emph{New Project} dialog to create a new song. 

Use the \emph{Project} menu, \emph{Add Track} submenu, to add a new MIDI track. 

Use the pencil tool to draw a \emph{Part} on the track a few measures long. Write some music in the \emph{Part} using the \emph{Event} editor or the \emph{Score} editor. 

Use the \emph{Devices} menu (or the F11 key) to open the \emph{VST Instruments} dialog. 

Click on one of the \emph{No VST Instrument} labels, and select \emph{\_CsoundVST} from the list that pops up. 

Click on the \emph{e} (for edit) button to open the \emph{\_CsoundVST} dialog. 

Click on the \emph{Open} button to bring up the file selector dialog. Navigate to a directory containing a Csound csd file suitable for MIDI performance, such as csound/CsoundVST/examples/CsoundVST.csd. Click on the OK button to load the file. You can also open and import a suitable \texttt{.orc} and \texttt{.sco} file as described above. 

Click on the \emph{VST Instruments} dialog's on/off button to turn it on. This should compile the Csound orchestra. \emph{Note: If you don't compile the orchestra, you won't be able to assign the plugin to a track.} 

In the \emph{Cubase Track Inspector}, click on the \emph{out: Not Assigned} label and select \emph{\_CsoundVST} from the list that pops up. 

On the ruler at the top of the \emph{Arrangement} window, select the loop end point and drag it to the end of your part, then click on the loop button to enable looping. 

Click on the \emph{play} button on the \emph{Transport} bar. You should hear your music played by CsoundVST. 

Try assigning your track to different channels; a different Csound instrument will perform each channel. 

When you save your song, your Csound orchestra will be saved as part of the song and re-loaded when you re-load the song. 

You can click on the \emph{Orchestra} tab and edit your Csound instruments while CsoundVST is playing. To hear your changes, just click on the CsoundVST \emph{Perform} button to recompile the orchestra. 

You can assign up to 16 channels to a single CsoundVST plugin. However, you can't have more than one CsoundVST plugin in the same song! 

\section{Building}

The latest Csound source code is available through the Concurrent Versions System (CVS)(\url{http://www.cvshome.org}). To download Csound sources using CVS, run the following commands:

\begin{lstlisting}
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/csound login 
 
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/csound co csound5 
\end{lstlisting}

Information about accessing the CVS repository may be found in the SourceForge document ``Basic Introduction to CVS and SourceForge.net (SF.net) Project CVS Services''. 

If you wish to become a Csound developer, obtain a SourceForge login, and then apply to John ffitch at the \url{http://www.sourceforge.net/projects/csound} site.

Csound and CsoundVST are built using the Python package \texttt{scons}, not with makefiles or GNU autotools. Experience shows that \texttt{scons} build systems are easier to write, easier to use, and run faster than autotools build systems. The only file used to build the entire Csound system is the \texttt{SConstruct} file, which is a Python script run by the \texttt{scons} shell script.

To build Csound 5:
\begin{enumerate}
\item Obtain the Csound source code from a SourceForge Csound 5 package file, or from SourceForge CVS.
\item Install and configure the following software packages:
\begin{enumerate}
\item Python (required) for running the build (also used for CsoundVST scripting), from \texttt{http://www.python.org}.
\item SCons (required) for running the build, from \url{http://www.scons.org}.
\item \texttt{libsndfile} (required) for reading and writing soundfiles, from \url{http://www.mega\-nerd.com/libsndfile/}.
\item PortAudio for reading and writing real-time audio, from \url{http://www.portaudio.com/}.
\item FLTK version 1.1.x for displaying graphs of function tables, and for widget opcodes, from \url{http://www.fltk.org}.
\end{enumerate}
\end{enumerate}

If you also want to build CsoundVST, you must configure the FLTK libraries to enable threads (\texttt{./configure ---enable-threads}). And you will need to install these additional packages:

\begin{enumerate}
\item The Software Interface and Wrapper Generator (SWIG) for generating Python interfaces to CsoundVST (required for CsoundVST), from \url{http://www.swig.org}.
\item The boost C++ template libraries for random numbers and linear algebra (required for CsoundVST), from \url{http://www.boost.org}. The CsoundVST \texttt{Random} class requires that boost must be later than version 1.32.1. I used the current CVS version.
\end{enumerate}

\subsection{Platforms}

Currently, Csound 5 builds and runs on Windows using either the Cygwin environment (\url{http://www.cygwin.com}), or the MinGW  (\url{http://www.mingw.org}) environment with the MSys shell (\url{http://www.mingw.org/msys.shtml}). Both of these environments are free, open source, and emulate the standard Unix/Linux environment and tools. On Linux, Csound 5 builds using the standard tools. Unix should work the same way as Linux.

On Windows, the Cygwin build procedure is more like the Linux one. However, the MinGW build is preferred, since the resulting executables do not require the Cygwin DLLs and run faster.

\subsubsection{Linux}

If you have properly installed all the dependencies mentioned above, you can build Csound 5 and CsoundVST simply by opening a console, changing to the \texttt{csound5} directory, and executing the \texttt{scons} command. To see the various configuration options, execute \texttt{scons -h}.

\subsubsection{Windows with Cygwin}

The build procedure for Cygwin is identical to Linux. However, Cygwin comes with its own customized version of Python, while CsoundVST uses the regular version of Python from \url{http://www.python.org}, which is built with Microsoft Visual C++. Make sure to install SCons in the Cygwin version of Python, and use that version for the build, even though CsoundVST will use the Windows version of Python.

\subsubsection{Windows with MinGW and MSys}

For MinGW, you may need to patch versions of SCons earlier than \texttt{0.96.1} as follows. Change line 51 of \texttt{SCons/Tool/mingw.py} from:

\begin{lstlisting}
cmd = SCons.Util.CLVar('$SHLINK', '$SHLINKFLAGS')
\end{lstlisting}
to:
\begin{lstlisting}
cmd = SCons.Util.CLVar(['$SHLINK', '$SHLINKFLAGS']) 
\end{lstlisting}

It is highly recommend that you update your MinGW installation from the SourceForge site to the ``current'' level for core gcc, g++, binutils,  utils, and the Windows API headers and libraries (w32api).

Rebuild and install a version of libsndfile no earlier than \url{http://www.mega-nerd.com/tmp/libsndfile-1.0.10pre4.tar.gz}

PortAudio works with either the Windows multimedia libaries (\texttt{./configure ---with-winapi=wmme}) or with ASIO (\texttt{./configure ---with-winapi=asio}). At this time, Low-latency on Windows is only feasible with ASIO, but it is not as robust as the multimedia library.

The build procedure for MinGW is similar, but not identical, to the Cygwin procedure. The MSys shell does not allow the user to execute Python commands directly. Therefore, you need to install the \emph{Windows} versions of Python and SCons, make sure that Python is in your Windows executable path, and run the build like this:

\begin{lstlisting}
$$ python c:/tools/python23/scripts/scons
\end{lstlisting}

You may also need to customize the \texttt{custom.py} file to declare to \texttt{scons} the locations of required header files and libraries, since on Windows there is no standard location for these as there is on Unix and Linux. You will not need to modify \texttt{custom.py} if you install all third-party libraries in the MSys \texttt{/usr/local/include} and \texttt{/usr/local/lib} directories.

\section{Extending}
Csound uses plugin unit generators. These are dynamic link libraries (DLLs) on Windows, and loadable modules (shared libraries that are \texttt{dlopen}ed) on Linux. It is relatively easy to extend Csound by writing new unit generators in C or C++.

The following assumes you already know how to make a regular Csound unit generator. If you don't, consult the Csound language documentation.
Supposing that your unit generator is named \texttt{xxx}, perform the following steps:
\begin{enumerate}
\item Write your \texttt{xxx.c} and \texttt{xxx.h} file as you would for a regular Csound unit generator. Put these files in the \texttt{csound5/Opcodes} directory.
\item \texttt{\#include "csdl.h"} in your unit generator sources. This causes the plugin development environment to emulate the regular Csound unit generator development environment.
\item Add your \texttt{OENTRY} records and unit generator registration functions at the bottom of your C file. Example (but you can have as many unit generators in one plugin as you like):
\begin{lstlisting}
\#define S sizeof

static OENTRY localops[] = {
{ "xxx", S(XXX), 5, "a", "ao", (SUBR)xxxset, NULL, (SUBR)xxx}
};

/*
 * The following macro from csdl.h defines 
 * the "opcode_size()" and "opcode_init()" 
 * opcode registration functions for the localops table.
 */
LINKAGE
\end{lstlisting}
\item Add your plugin as a new target in the plugin opcodes section of the \texttt{SConstruct} build file:
\begin{lstlisting}
pluginEnvironment.SharedLibrary('xxx', 
    Split('''Opcodes/xxx.c 
    Opcodes/another_file_used_by_xxx.c 
    Opcodes/yet_another_file_used_by_xxx.c'''))
\end{lstlisting}
\item Run the Csound 5 build in the regular way.
\end{enumerate}		

\subsection{About \texttt{OENTRY}}

The \texttt{OENTRY} structure (see \texttt{include/csoundCore.h}, \texttt{Engine/entry1.c}, and \texttt{Engine/rdorch.c}) contains the following fields:

\begin{lstlisting}
name, dspace, thread, outarg, inargs, isub, ksub, asub, dsub
\end{lstlisting}

\begin{description}  
	\item[\texttt{dspace}] There are two types of opcodes, polymorphic and non-polymorphic. For non-polymorphic opcodes, the \texttt{dspace} flag specifies the size of the opcode structure in bytes, and arguments are always passed to the opcode at the same rate. Polymorphic opcodes can accept arguments at different rates, and those arguments are actually dispatched to other opcodes as determined by the \texttt{dspace} flag and the following naming convention:

	\begin{description}
		\item[\texttt{0xffff}] The type of the first argument determines which unit generator function is actually called: \texttt{XXX} $\Longrightarrow$ \texttt{XXX\_a}, \texttt{XXX\_i}, or \texttt{XXX\_k}.
		\item[\texttt{0xfffe}] The types of the first two arguments determine which unit generator function is actually called:  \texttt{XXX} $\Longrightarrow$ \texttt{XXX\_aa}, \texttt{XXX\_ak}, \texttt{XXX\_ka}, or \texttt{XXX\_kk}, as in the \texttt{oscil} unit generator.
		\item[\texttt{0xfffd}] Refers to one argument, but does not allow \texttt{i} type, as in the \texttt{peak} unit generator.
		\item[\texttt{0xfffc}] Similar to \texttt{0xfffe}, but deals with division by zero --- thus, allows \texttt{a}, \texttt{k} and \texttt{i} type arguments.
	\end{description}

	\item[\texttt{thread}] Specifies the rate(s) at which the unit generator's functions are called, as follows:
	
			\begin{center}
			\begin{tabular*}{280pt}[t]{cl}
			\texttt{thread} & Description \\
			\hline
			\texttt{0} & i-rate \emph{or} k-rate (\texttt{B} out only) \\
			\texttt{1} & i-rate \\
			\texttt{2} & k-rate \\
			\texttt{3} & i-rate \emph{and} k-rate\\
			\texttt{4} & a-rate \\
			\texttt{5} & i-rate \emph{and} a-rate \\
			\texttt{7} & i-rate \emph{and} (k-rate \emph{or} a-rate) \\
			\end{tabular*}
			\end{center}
	
	\item[\texttt{outargs}] Lists the return values of the unit generator functions, if any.  The types allowed are:

			\begin{center}
			\begin{tabular*}{280pt}[t]{cl}
			Type & Description \\
			\hline
			\texttt{i} & i-rate scalar \\
			\texttt{k} & k-rate scalar \\
			\texttt{a} & a-rate vector \\
			\texttt{x} & k-rate scalar or a-rate vector \\
			\texttt{w} & w-rate spectral data type \\
			\texttt{f} & f-rate streaming pvoc fsig type \\
			\texttt{m} & multiple outargs (1 to 4 allowed) \\
			\end{tabular*}
			\end{center}
					
	\item[\texttt{inargs}] Lists the arguments the unit generator functions take, if any.  The types allowed are: 

			\begin{center}
			\begin{tabular*}{280pt}[t]{cl}
			Type & Description \\
			\hline
			\texttt{i} & i-rate scalar \\
			\texttt{k} & k-rate scalar \\
			\texttt{a} & a-rate scalar \\
			\texttt{x} & k-rate scalar or a-rate vector \\
			\texttt{w} & w-rate spectral data type \\
			\texttt{f} & f-rate streaming pvoc fsig type \\
			\texttt{S} & string \\
			\texttt{B} & \\
			\texttt{l} & \\
			\texttt{m} & begins an indefinite list of iargs (any count) \\
			\texttt{M} & begins an indefinite list of args (any count and rate) \\
			\texttt{n} & begins an indefinite list of iargs (must be an odd count) \\
			\texttt{o} & optional, defaulting to 0 \\
			\texttt{p} & optional, defaulting to 1 \\
			\texttt{q} & optional, defaulting to 10 \\
			\texttt{v} & optional, defaulting to .5 \\ 
			\texttt{j} & optional, defaulting to -1 \\
			\texttt{h} & optional, defaulting to 127 \\
			\texttt{y} & begins an indefinite list of aargs (any count) \\ 
			\texttt{z} & begins indefinite list of kargs (any count) \\
			\texttt{Z} & begins alternating \texttt{kakaka...} list (any count) \\
			\end{tabular*}
			\end{center}

	\item[\texttt{isub}] The address of the unit generator function (of type \texttt{int (*SUBR)(void *)}) that is called at i-time, or null for no function.
	\item[\texttt{ksub}] The address of the unit generator function (of type \texttt{int (*SUBR)(void *)}) that is called at k-rate, or null for no function.
	\item[\texttt{asub}] The address of the unit generator function (of type \texttt{int (*SUBR)(void *)}) that is called at a-rate, or null for no function.
	\item[\texttt{dsub}] The address of the unit generator function (of type \texttt{int (*SUBR)(void *)}) that is called after performance, or null for no function.

\end{description}

\section{Licenses}

\subsection{Csound and CsoundVST}

Csound is \copyright 1991-2003 by Barry Vercoe and John ffitch.

CsoundVST is \copyright 2001-2004 by Michael Gogins.

Csound and CsoundVST are free software; you can redistribute them and/or modify them under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

Csound and CsoundVST are distributed in the hope that they will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with Csound and CsoundVST; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
\subsection{Virtual Synthesis Technology}
Virtual Synthesis Technology (VST) PlugIn interface technology by Steinberg Soft- und Hardware GmbH. 

CsoundVST source code contains modified versions of source code files from the VST SDK distributed by Steinberg. \emph{These files are to be used only for building CsoundVST.} You are \emph{not} licensed to use these files for any other purpose. If you make a derived product based on CsoundVST or the modified VST source files herein, you \emph{must} apply to Steinberg for your own license to use the VST SDK.
\section{Contributors}
Csound contains contributions from musicians, scientists, and programmers from around the world. They include (but are not limited to): 
\begin{itemize}
\item Allan Lee 
\item Andres Cabrera
\item Barry Vercoe
\item Bill Gardner 
\item Bill Verplank 
\item Dan Ellis 
\item David Macintyre 
\item Eli Breder 
\item Gabriel Maldonado  
\item Greg Sullivan 
\item Hans Mikelson 
\item Istvan Varga 
\item Jean Piche 
\item John ffitch 
\item John Ramsdell 
\item Marc Resibois 
\item Mark Dolson 
\item Matt Ingalls 
\item Max Mathews 
\item Michael Casey 
\item Michael Clark 
\item Michael Gogins 
\item Mike Berry 
\item Paris Smaragdis 
\item Perry Cook 
\item Peter Neubacker 
\item Peter Nix 
\item Rasmus Ekman 
\item Richard Dobson 
\item Richard Karpen 
\item Rob Shaw 
\item Robin Whittle 
\item Sean Costello 
\item Steven Yi 
\item Tom Erbe 
\item Victor Lazzarini  
\item Ville Pulkki 
\end{itemize}

\section{To Do}

This is a ``to do'' list, not necessarily complete, and in no particular order of priority or time, for Csound and CsoundVST:

\begin{enumerate}
\item See also the \texttt{To-fix-and-do} file in the \texttt{csound5} directory.
\item Create better examples, especially to demonstrate the use of Python and of VST plugins. One example should be a live performance instrument with a Python GUI that controls instrument parameters or algorithmic composition parameters in real time.
\item All Csound documentation in this one PDF.
\item Complete the work of making Csound multi-instantiable.
\end{enumerate}

\input{doc/manual/a.tex}
\input{doc/manual/i.tex}

\end{document}