# Just Launched: You can now import projects and releases from Google Code onto SourceForge

We are excited to release new functionality to enable a 1-click import from Google Code onto the Allura platform on SourceForge. You can import tickets, wikis, source, releases, and more with a few simple steps.

## [998c01]: refman_header.tex Maximize Restore History

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 % C S O U N D 5 A P I R E F E R E N C E M A N U A L % The manual is produced from 2 sources: this header document for new features and users' guide, % and autogenerated Doxygen LaTeX files for Csound API reference documentation. To produce the entire manual: % 1. Run Doxygen in the csound5 directory. It will produce LaTeX output that includes the contents of this file, % as well as API documentation automatically generated from various Csound and CsoundVST header files. % 2. Doxygen will produce a doc/csound/latex/refman.tex file. Run pdflatex on this file to generate csound.pdf. You can % also run tex4ht on this file to produce an HTML form of the manual. Be sure to run in a mode that skips right on past % all the hundreds of LaTeX errors! % 3. Steps 1 and 3 are automated in SConstruct with the generatePdf=1 option. \documentclass[10pt,letterpaper,onecolumn]{scrbook} \usepackage{tocloft} \usepackage{stdclsdv} \usepackage{comment} \usepackage{vmargin} \usepackage{t1enc} \usepackage{fancyvrb} \usepackage{url} \usepackage{calc} \usepackage{array} \usepackage{scrpage2} \usepackage[pdftex]{graphicx} \usepackage{color} \usepackage{listings} \usepackage[latin1]{inputenc} \usepackage[english]{babel} \usepackage{doxygen} \usepackage{supertabular} \usepackage[pdftex, pagebackref=true, colorlinks=true, linkcolor=blue, pdfpagelabels, pdfstartpage=3 ]{hyperref} \pagestyle{scrheadings} \makeindex \definecolor{LstColor}{cmyk}{0.1,0.1,0,0.025} \setlength{\cftsecnumwidth}{4em} \lstset{language=c++,basicstyle=\ttfamily\scriptsize,commentstyle=\ttfamily\scriptsize,tabsize=2,breaklines,backgroundcolor=\color{LstColor},fontadjust=true,fancyvrb=true,moredelim=[is][\textbf]{\\emph\{}{\}}}. \setcounter{tocdepth}{1} \begin{document} \frontmatter \title{Csound and CsoundVST \\ API Reference Manual} \author{\emph{By} \\ Michael Gogins \\ \texttt{gogins@pipeline.com} \\ } \maketitle \tableofcontents[2] \frontmatter \mainmatter \pagenumbering{arabic} \setcounter{page}{1} \part{Licenses} \chapter{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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. \chapter{Manual} Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. \part{API Reference} \chapter{The Csound Application Programming Interfaces} The Csound Application Programming Interface (API) reference is contained in the chapters following this one. The Csound API actually consists of several APIs: \begin{itemize} \item \emph{The basic Csound C API.} Include \texttt{csound.h} (page \pageref{csound_8h}) and link with \texttt{libcsound.a}. This also includes the Cscore API (see below). \item \emph{The basic Csound C++ API.} Include \texttt{csound.hpp} (page \pageref{csound_8hpp}) and link with \texttt{libcsound.a}. \item \emph{The extended Csound C++ API.} Include \texttt{CppSound.hpp} (page \pageref{CppSound_8hpp}) and \texttt{CppSound.hpp} (page \pageref{CsoundFile_8hpp}) and link with \verb|libcsound.a| and \verb|lib_csnd.a|, which adds to the Csound C++ API a CsoundFile class (\ref{classCsoundFile}) for loading, saving, and editing Csound orchestra and score files. \item \emph{The CsoundVST C++ API.} Include \texttt{CsoundVST.hpp} (page \pageref{CsoundVST_8hpp}) and link with \verb|libcsound.a|, \verb|lib_csnd.a|, and \verb|libCsoundVST.a|. The \texttt{CsoundVST} class (\ref{classCsoundVST}) contains an instance of the \texttt{CppSound} class (\ref{classCppSound}), which adds to the Csound a basic graphical user interface for editing Csound files and running Csound, and provides a class hierarchy for doing algorithmic composition using Michael Gogins' concept of music graphs (also known as Silence). \item \emph{The Csound Python API.} Import the \texttt{csnd} Python extension module. This provides a complete Python wrapper for \texttt{csound.hpp} (page \pageref{csound_8hpp}), \texttt{CppSound} (\ref{classCppSound}), and \texttt{CsoundFile} (\ref{classCsoundFile}). The Python API provides a complete Python wrapper for the entire Csound C++ API, and the Csound C++ API reference also serves as a reference to the Python API. \item \emph{The CsoundVST Python API.} Import the \texttt{CsoundVST} Python extension module. The Python API provides a complete Python wrapper for the entire CsoundVST C++ API, including Silence, and the CsoundVST C++ API reference also serves as a reference to the Python API. \item \emph{An experimental LISP API.} \end{itemize} \section{An Example Using the Csound API} The Csound command--line program is itself built using the Csound API. Its code reads in full as follows: \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} \section{An Example Using the CsoundVST C++ 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. 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} int main(int argc, char **argv) { CsoundVST *csoundVST = CreateCsoundVST(); AEffEditor *editor = csoundVST->getEditor(); editor->open(0); if(argc == 2) { csoundVST->openFile(argv[1]); } return csoundVST->run(); } \end{lstlisting} \section{Cscore} Beginning with Csound 5, all of the Cscore functions described in the manual are now part of the Csound API, and they can be called from a program that calls the Csound library. All of the CScore functions are renamed in the Csound API. For example, \texttt{createv()} is now \texttt{cscoreCreateEvent()}, and \texttt{lcopy()} is now \texttt{cscoreListCopy()}. In addition, each function takes an additional first parameter that is a pointer to a \texttt{CSOUND} instance. You can find the details in the header file, \url{cscore.h}, which may be included with your Csound distribution, or if not, can be found in Csound CVS on SourceForge. Before you can use any of the Cscore API functions, you must create a \texttt{CSOUND} instance and initialize Cscore by calling \texttt{csoundInitializeCscore()} -- see \url{csound.h} for an explanation. An example main program that does all of this can be found in Csound CVS on SourceForge in \url{Top/cscormai.c}. You should add a function called \texttt{cscore()} with your own score-processing code. An example that does nothing except write the score back out unchanged can be found in the file \url{Top/cscore_internal.c}. To create your own standalone Cscore program, you must compile \url{cscormai.c} (or your own main program) and the file containing your \texttt{cscore()} function, and link them with the Csound API library. Everything that can be done using C as in the above examples can also be done in a similar manner in Python or any of the other Csound API languages.