|
18 | 18 | * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
|
19 | 19 | */
|
20 | 20 | #pragma once
|
21 |
| - |
22 |
| - /** |
23 |
| - * \page csoundac CsoundAC |
24 |
| - * |
25 |
| - * CsoundAC is a C++ class library for algorithmic music |
26 |
| - * composition with Csound. |
27 |
| - * |
28 |
| - * CsoundAC has C++, Java, Python, and Lua interfaces. |
29 |
| - * |
30 |
| - * CsoundAC implements the idea of a "music graph," similar to a scene |
31 |
| - * graph in 3-dimensional computer graphics. A composition is constructed |
32 |
| - * by assembling a directed acyclic graph of Node objects, which may generate |
33 |
| - * or transform Events that are collected in a Score. Each Node may have its |
34 |
| - * own local transformation of coordinagte system. The music graph |
35 |
| - * represents a model of a musical score. The Composition class provides |
36 |
| - * an abstract base class for managing a music graph. The MusicModel class |
37 |
| - * subclasses the Composition class to include the ability to store and |
38 |
| - * run a Csound orchestra. |
39 |
| - * |
40 |
| - * See the <a href="namespacecsound.html">csound</a> |
41 |
| - * namespace for information about the classes in CsoundAC. |
42 |
| - */ |
43 |
| - /** |
44 |
| - * \namespace csound |
45 |
| - * |
46 |
| - * The csound namespace contains classes for doing algorithmic composition, |
47 |
| - * and for rendering audio from algorithmically generated scores, |
48 |
| - * especially using Csound. |
49 |
| - * |
50 |
| - * All classes declared for CsoundAC should be #included in Silence.hpp. |
51 |
| - * |
52 |
| - * SWIG is run on Silence.hpp to generate wrappers for all CsoundAC classes |
53 |
| - * in other languages, especially scripting languages such as Python, |
54 |
| - * Therefore, all framework headers must be included in this header, |
55 |
| - * and all framework headers must use #ifdef SWIG to declare |
56 |
| - * the module and make other SWIG declarations (see Node.h for an extensive example). |
57 |
| - * The order of declaration is important to SWIG! |
58 |
| - * |
59 |
| - * It is also expected that doxygen will be used to generate documentation |
60 |
| - * from comments in the framework header files. |
61 |
| - */ |
62 |
| - /** \page csound Csound |
63 |
| - * |
64 |
| - * Csound is a sound and music computing system. It was originally written |
65 |
| - * by Barry Vercoe at the Massachusetts Institute of Technology in |
66 |
| - * 1984 as the first C language version of this type of |
67 |
| - * software. Since then Csound has received numerous contributions |
68 |
| - * from researchers, programmers, and musicians from around the world. |
69 |
| - * |
70 |
| - * \section silence_section_api_outline Outline of the API |
71 |
| - * |
72 |
| - * \subsection silence_section_api_apilist The Csound Application Programming Interfaces |
73 |
| - * |
74 |
| - * The Csound Application Programming Interface (API) reference is contained |
75 |
| - * herein. |
76 |
| - * The Csound API actually consists of several APIs: |
77 |
| - * |
78 |
| - * - The basic Csound C API. Include csound.h and link with libcsound.a. |
79 |
| - * This also includes the Cscore API (see below). |
80 |
| - * - The basic Csound C++ API. Include csound.hpp and link with libcsound.a. |
81 |
| - * - The interfaces API, includes a number of auxiliary C++ classes, which |
82 |
| - * add functionality and support the wrapping of the Csound API by various |
83 |
| - * languages (e.g. Python, Java, Lua). |
84 |
| - * |
85 |
| - * \b Purposes |
86 |
| - * |
87 |
| - * The purposes of the Csound API are as follows: |
88 |
| - * |
89 |
| - * \li Declare a stable public application programming interface (API) |
90 |
| - * for Csound in csound.h. This is the only header file that needs |
91 |
| - * to be \#included by users of the Csound API. |
92 |
| - * |
93 |
| - * \li Hide the internal implementation details of Csound from users of |
94 |
| - * the API, so that development of Csound can proceed without affecting |
95 |
| - * code that uses the API. |
96 |
| - * |
97 |
| - * \b Users |
98 |
| - * |
99 |
| - * Users of the Csound API fall into two main categories: hosts and plugins. |
100 |
| - * |
101 |
| - * \li Hosts are applications that use Csound as a software synthesis engine. |
102 |
| - * Hosts can link with the Csound API either statically or dynamically. |
103 |
| - * |
104 |
| - * \li Plugins are shared libraries loaded by Csound at run time to implement |
105 |
| - * external opcodes and/or drivers for audio or MIDI input and output. |
106 |
| - * Plugin opcodes need only include the csdl.h header which brings all |
107 |
| - * necessary functions and data structures. |
108 |
| - * Plugins can be written in C or C++. For C++, OOP support is given through |
109 |
| - * `include/plugin.h` (using the Csound allocator, for opcodes |
110 |
| - * that do not involve standard C++ library collections) or |
111 |
| - * `include/OpcodeBase.hpp` (using the standard ++ allocator, for opcodes |
112 |
| - * that do use standard C++ library collections). |
113 |
| - * |
114 |
| - * \section silence_section_api_c_example Examples Using the Csound (host) API |
115 |
| - * |
116 |
| - * The Csound command--line program is itself built using the Csound API. |
117 |
| - * Its code reads (in outline) as follows: |
118 |
| - * |
119 |
| - * \code |
120 |
| - * #include "csound.h" |
121 |
| - * |
122 |
| - * int main(int argc, char **argv) |
123 |
| - * { |
124 |
| - * void *csound = csoundCreate(0); |
125 |
| - * int result = csoundCompile(csound, argc, argv); |
126 |
| - * if(!result) { |
127 |
| - * while(csoundPerformKsmps(csound) == 0){} |
128 |
| - * csoundCleanup(csound); |
129 |
| - * } |
130 |
| - * csoundDestroy(csound); |
131 |
| - * return result; |
132 |
| - * } |
133 |
| - * \endcode |
134 |
| - * |
135 |
| - * Csound code can also be supplied directly using strings, either as |
136 |
| - * a multi-section CSD (with the same format as CSD files) or |
137 |
| - * directly as a string. It can be compiled any number of times |
138 |
| - * before or during performance. |
139 |
| - * |
140 |
| - * \subsection silence_s1 Using a CSD text |
141 |
| - * |
142 |
| - * System options can be passed via the CSD text before the engine |
143 |
| - * is started. These are ignored in subsequent compilations. |
144 |
| - * |
145 |
| - * \code |
146 |
| - * #include "csound.h" |
147 |
| - * |
148 |
| - * const char *csd_text = |
149 |
| - * "<CsoundSynthesizer> \n" |
150 |
| - * "<CsOptions> -odac </CsOptions> \n" |
151 |
| - * "<CsInstruments> \n" |
152 |
| - * "instr 1 \n" |
153 |
| - * " out(linen(oscili(p4,p5),0.1,p3,0.1)) \n" |
154 |
| - * "endin \n" |
155 |
| - * "</CsInstruments> \n" |
156 |
| - * "<CsScore> \n" |
157 |
| - * "i1 0 5 1000 440 \n" |
158 |
| - * "</CsScore> \n" |
159 |
| - * "</CsoundSynthesizer> \n"; |
160 |
| - * |
161 |
| - * int main(int argc, char **argv) |
162 |
| - * { |
163 |
| - * void *csound = csoundCreate(0); |
164 |
| - * int result = csoundCompileCsdText(csound, csd_text); |
165 |
| - * result = csoundStart(csound); |
166 |
| - * while (1) { |
167 |
| - * result = csoundPerformKsmps(csound); |
168 |
| - * if (result != 0) { |
169 |
| - * break; |
170 |
| - * } |
171 |
| - * } |
172 |
| - * result = csoundCleanup(csound); |
173 |
| - * csoundReset(csound); |
174 |
| - * csoundDestroy(csound); |
175 |
| - * return result; |
176 |
| - * } |
177 |
| - * \endcode |
178 |
| - * |
179 |
| - * \subsection silence_s2 Using Csound code directly. |
180 |
| - * |
181 |
| - * Options can be passed via csoundSetOption() before the engine starts. |
182 |
| - * |
183 |
| - * \code |
184 |
| - * #include "csound.h" |
185 |
| - * |
186 |
| - * const char *orc_text = |
187 |
| - * "instr 1 \n" |
188 |
| - * " out(linen(oscili(p4,p5),0.1,p3,0.1)) \n" |
189 |
| - * "endin \n"; |
190 |
| - * |
191 |
| - * const char *sco_text = "i1 0 5 1000 440 \n"; |
192 |
| - * |
193 |
| - * int main(int argc, char **argv) |
194 |
| - * { |
195 |
| - * void *csound = csoundCreate(0); |
196 |
| - * int result = csoundSetOption(csound, "-d"); |
197 |
| - * result = csoundSetOption(csound, "-odac"); |
198 |
| - * result = csoundStart(csound); |
199 |
| - * result = csoundCompileOrc(csound, orc_text); |
200 |
| - * result = csoundReadScore(csound, sco_text); |
201 |
| - * while (1) { |
202 |
| - * result = csoundPerformKsmps(csound); |
203 |
| - * if (result != 0) { |
204 |
| - * break; |
205 |
| - * } |
206 |
| - * } |
207 |
| - * result = csoundCleanup(csound); |
208 |
| - * csoundReset(csound); |
209 |
| - * csoundDestroy(csound); |
210 |
| - * return result; |
211 |
| - * } |
212 |
| - * \endcode |
213 |
| -
|
214 |
| - * |
215 |
| - * Everything that can be done using C as in the above examples can also be done |
216 |
| - * in a similar manner in Python or any of the other Csound API languages. |
217 |
| - * |
218 |
| - * \file csound.h |
219 |
| - * |
220 |
| - * \brief Declares the public Csound application programming interface (API). |
221 |
| - * \author John P. ffitch, Michael Gogins, Matt Ingalls, John D. Ramsdell, |
222 |
| - * Istvan Varga, Victor Lazzarini, Andres Cabrera and Steven Yi. |
223 |
| - * |
224 |
| - * Hosts using the Csound API must \#include <csound.h>, and link with the |
225 |
| - * Csound API library. Plugin libraries should \#include <csdl.h> to get |
226 |
| - * access to the API function pointers in the CSOUND structure, and do not |
227 |
| - * need to link with the Csound API library. |
228 |
| - * Only one of csound.h and csdl.h may be included by a compilation unit. |
229 |
| - * |
230 |
| - * Hosts must first create an instance of Csound using the \c csoundCreate |
231 |
| - * API function. When hosts are finished using Csound, they must destroy the |
232 |
| - * instance of csound using the \c csoundDestroy API function. |
233 |
| - * Most of the other Csound API functions take the Csound instance as their |
234 |
| - * first argument. |
235 |
| - * Hosts can only call the standalone API functions declared in csound.h. |
236 |
| - * |
237 |
| - * Here is the complete code for the simplest possible Csound API host, |
238 |
| - * a command-line Csound application: |
239 |
| - * |
240 |
| - * \code |
241 |
| - * |
242 |
| - * #include <csound.h> |
243 |
| - * |
244 |
| - * int main(int argc, char **argv) |
245 |
| - * { |
246 |
| - * CSOUND *csound = csoundCreate(NULL); |
247 |
| - * int result = csoundCompile(csound, argc, argv); |
248 |
| - * if (!result) |
249 |
| - * result = csoundPerform(csound); |
250 |
| - * csoundDestroy(csound); |
251 |
| - * return (result >= 0 ? 0 : result); |
252 |
| - * } |
253 |
| - * |
254 |
| - * \endcode |
255 |
| - * |
256 |
| - * All opcodes, including plugins, receive a pointer to their host |
257 |
| - * instance of Csound as the first argument. Therefore, plugins MUST NOT |
258 |
| - * compile, perform, or destroy the host instance of Csound, and MUST call |
259 |
| - * the Csound API function pointers off the Csound instance pointer. |
260 |
| - * |
261 |
| - * \code |
262 |
| - * MYFLT sr = csound->GetSr(csound); |
263 |
| - * \endcode |
264 |
| - * |
265 |
| - * In general, plugins should ONLY access Csound functionality through the |
266 |
| - * API function pointers and public members of the #CSOUND_ structure. |
267 |
| - * |
| 21 | +/** |
268 | 22 | * \section silence_section_licenses License
|
269 | 23 | *
|
270 | 24 | * \subsection silence_section_csound_license Csound
|
|
0 commit comments