1 /* 2 csound.h: 3 4 Copyright (C) 2003 2005 2008 2013 by John ffitch, Istvan Varga, 5 Mike Gogins, Victor Lazzarini, 6 Andres Cabrera, Steven Yi 7 8 This file is part of Csound. 9 10 The Csound Library is free software; you can redistribute it 11 and/or modify it under the terms of the GNU Lesser General Public 12 License as published by the Free Software Foundation; either 13 version 2.1 of the License, or (at your option) any later version. 14 15 Csound is distributed in the hope that it will be useful, 16 but WITHOUT ANY WARRANTY; without even the implied warranty of 17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 GNU Lesser General Public License for more details. 19 20 You should have received a copy of the GNU Lesser General Public 21 License along with Csound; if not, write to the Free Software 22 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 23 02110-1301 USA 24 */ 25 26 #ifndef CSOUND_H 27 #define CSOUND_H 28 /*! \mainpage 29 * 30 * Csound is a sound and music computing system. It was originally written 31 * by Barry Vercoe at the Massachusetts Institute of Technology in 32 * 1984 as the first C language version of this type of 33 * software. Since then Csound has received numerous contributions 34 * from researchers, programmers, and musicians from around the world. 35 * 36 * \section section_api_outline Outline of the API 37 * 38 * \subsection section_api_apilist The Csound Application Programming Interfaces 39 * 40 * The Csound Application Programming Interface (API) reference is contained 41 * herein. 42 * The Csound API actually consists of several APIs: 43 * 44 * - The basic Csound C API. Include csound.h and link with libcsound.a. 45 * This also includes the Cscore API (see below). 46 * - The basic Csound C++ API. Include csound.hpp and link with libcsound.a. 47 * - The interfaces API, includes a number of auxiliary C++ classes, which 48 * add functionality and support the wrapping of the Csound API by various 49 * languages (e.g. Python, Java, Lua). 50 * 51 * \b Purposes 52 * 53 * The purposes of the Csound API are as follows: 54 * 55 * \li Declare a stable public application programming interface (API) 56 * for Csound in csound.h. This is the only header file that needs 57 * to be \#included by users of the Csound API. 58 * 59 * \li Hide the internal implementation details of Csound from users of 60 * the API, so that development of Csound can proceed without affecting 61 * code that uses the API. 62 * 63 * \b Users 64 * 65 * Users of the Csound API fall into two main categories: hosts and plugins. 66 * 67 * \li Hosts are applications that use Csound as a software synthesis engine. 68 * Hosts can link with the Csound API either statically or dynamically. 69 * 70 * \li Plugins are shared libraries loaded by Csound at run time to implement 71 * external opcodes and/or drivers for audio or MIDI input and output. 72 * Plugin opcodes need only include the csdl.h header which brings all 73 * necessary functions and data structures. 74 * Plugins can be written in C or C++. For C++, OOP support is given through 75 * `include/plugin.h` (using the Csound allocator, for opcodes 76 * that do not involve standard C++ library collections) or 77 * `include/OpcodeBase.hpp` (using the standard ++ allocator, for opcodes 78 * that do use standard C++ library collections). 79 * 80 * \section section_api_c_example Examples Using the Csound (host) API 81 * 82 * The Csound command--line program is itself built using the Csound API. 83 * Its code reads (in outline) as follows: 84 * 85 * \code 86 * #include "csound.h" 87 * 88 * int main(int argc, char **argv) 89 * { 90 * void *csound = csoundCreate(0); 91 * int result = csoundCompile(csound, argc, argv); 92 * if(!result) { 93 * while(csoundPerformKsmps(csound) == 0){} 94 * csoundCleanup(csound); 95 * } 96 * csoundDestroy(csound); 97 * return result; 98 * } 99 * \endcode 100 * 101 * Csound code can also be supplied directly using strings, either as 102 * a multi-section CSD (with the same format as CSD files) or 103 * directly as a string. It can be compiled any number of times 104 * before or during performance. 105 * 106 * \subsection s1 Using a CSD text 107 * 108 * System options can be passed via the CSD text before the engine 109 * is started. These are ignored in subsequent compilations. 110 * 111 * \code 112 * #include "csound.h" 113 * 114 * const char *csd_text = 115 * "<CsoundSynthesizer> \n" 116 * "<CsOptions> -odac </CsOptions> \n" 117 * "<CsInstruments> \n" 118 * "instr 1 \n" 119 * " out(linen(oscili(p4,p5),0.1,p3,0.1)) \n" 120 * "endin \n" 121 * "</CsInstruments> \n" 122 * "<CsScore> \n" 123 * "i1 0 5 1000 440 \n" 124 * "</CsScore> \n" 125 * "</CsoundSynthesizer> \n"; 126 * 127 * int main(int argc, char **argv) 128 * { 129 * void *csound = csoundCreate(0); 130 * int result = csoundCompileCsdText(csound, csd_text); 131 * result = csoundStart(csound); 132 * while (1) { 133 * result = csoundPerformKsmps(csound); 134 * if (result != 0) { 135 * break; 136 * } 137 * } 138 * result = csoundCleanup(csound); 139 * csoundReset(csound); 140 * csoundDestroy(csound); 141 * return result; 142 * } 143 * \endcode 144 * 145 * \subsection s2 Using Csound code directly. 146 * 147 * Options can be passed via csoundSetOption() before the engine starts. 148 * 149 * \code 150 * #include "csound.h" 151 * 152 * const char *orc_text = 153 * "instr 1 \n" 154 * " out(linen(oscili(p4,p5),0.1,p3,0.1)) \n" 155 * "endin \n"; 156 * 157 * const char *sco_text = "i1 0 5 1000 440 \n"; 158 * 159 * int main(int argc, char **argv) 160 * { 161 * void *csound = csoundCreate(0); 162 * int result = csoundSetOption(csound, "-d"); 163 * result = csoundSetOption(csound, "-odac"); 164 * result = csoundStart(csound); 165 * result = csoundCompileOrc(csound, orc_text); 166 * result = csoundReadScore(csound, sco_text); 167 * while (1) { 168 * result = csoundPerformKsmps(csound); 169 * if (result != 0) { 170 * break; 171 * } 172 * } 173 * result = csoundCleanup(csound); 174 * csoundReset(csound); 175 * csoundDestroy(csound); 176 * return result; 177 * } 178 * \endcode 179 180 * 181 * Everything that can be done using C as in the above examples can also be done 182 * in a similar manner in Python or any of the other Csound API languages. 183 * 184 * \file csound.h 185 * 186 * \brief Declares the public Csound application programming interface (API). 187 * \author John P. ffitch, Michael Gogins, Matt Ingalls, John D. Ramsdell, 188 * Istvan Varga, Victor Lazzarini, Andres Cabrera and Steven Yi. 189 * 190 * Hosts using the Csound API must \#include <csound.h>, and link with the 191 * Csound API library. Plugin libraries should \#include <csdl.h> to get 192 * access to the API function pointers in the CSOUND structure, and do not 193 * need to link with the Csound API library. 194 * Only one of csound.h and csdl.h may be included by a compilation unit. 195 * 196 * Hosts must first create an instance of Csound using the \c csoundCreate 197 * API function. When hosts are finished using Csound, they must destroy the 198 * instance of csound using the \c csoundDestroy API function. 199 * Most of the other Csound API functions take the Csound instance as their 200 * first argument. 201 * Hosts can only call the standalone API functions declared in csound.h. 202 * 203 * Here is the complete code for the simplest possible Csound API host, 204 * a command-line Csound application: 205 * 206 * \code 207 * 208 * #include <csound.h> 209 * 210 * int main(int argc, char **argv) 211 * { 212 * CSOUND *csound = csoundCreate(NULL); 213 * int result = csoundCompile(csound, argc, argv); 214 * if (!result) 215 * result = csoundPerform(csound); 216 * csoundDestroy(csound); 217 * return (result >= 0 ? 0 : result); 218 * } 219 * 220 * \endcode 221 * 222 * All opcodes, including plugins, receive a pointer to their host 223 * instance of Csound as the first argument. Therefore, plugins MUST NOT 224 * compile, perform, or destroy the host instance of Csound, and MUST call 225 * the Csound API function pointers off the Csound instance pointer. 226 * 227 * \code 228 * MYFLT sr = csound->GetSr(csound); 229 * \endcode 230 * 231 * In general, plugins should ONLY access Csound functionality through the 232 * API function pointers and public members of the #CSOUND_ structure. 233 * 234 * \section section_licenses License 235 * 236 * \subsection section_csound_license Csound 237 * 238 * Copyright (C) 2001-2013 John ffitch, Michael Gogins, Victor Lazzarini, 239 * Steven Yi, Istvan Varga, Andres Cabrera 240 * 241 * This software is free software; you can redistribute it and/or 242 * modify it under the terms of the GNU Lesser General Public 243 * License as published by the Free Software Foundation; either 244 * version 2.1 of the License, or (at your option) any later version. 245 * 246 * This software is distributed in the hope that it will be useful, 247 * but WITHOUT ANY WARRANTY; without even the implied warranty of 248 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 249 * Lesser General Public License for more details. 250 * 251 * You should have received a copy of the GNU Lesser General Public 252 * License along with this software; if not, write to the Free Software 253 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 254 */ 255 256 /* 257 * Platform-dependent definitions and declarations. 258 */ 259 260 #if (defined(WIN32) || defined(_WIN32)) && !defined(SWIG) 261 # if defined(__BUILDING_LIBCSOUND) 262 # define PUBLIC __declspec(dllexport) 263 # define PUBLIC_DATA __declspec(dllexport) 264 # else 265 # define PUBLIC __declspec(dllexport) 266 # define PUBLIC_DATA __declspec(dllimport) 267 # endif 268 #elif defined(__GNUC__) && (__GNUC__ >= 4) /* && !defined(__MACH__) */ 269 # define PUBLIC __attribute__ ( (visibility("default")) ) 270 # define PUBLIC_DATA __attribute__ ( (visibility("default")) ) 271 #else 272 # define PUBLIC 273 # define PUBLIC_DATA 274 #endif 275 276 #if defined(MSVC) 277 # include <intrin.h> /* for _InterlockedExchange */ 278 #endif 279 280 #if defined(__MACH__) 281 // on OSX 10.6 i386 does not have all builtins 282 #if defined(MAC_OS_X_VERSION_10_6) 283 #ifdef HAVE_ATOMIC_BUILTIN 284 #ifndef __x86_64__ 285 #undef HAVE_ATOMIC_BUILTIN 286 #endif 287 #endif 288 #endif 289 #endif 290 291 /** 292 * Enables Python interface. 293 */ 294 295 #ifdef SWIG 296 #define CS_PRINTF2 297 #define CS_PRINTF3 298 #include "float-version.h" 299 #ifndef __MYFLT_DEF 300 #define __MYFLT_DEF 301 #ifndef USE_DOUBLE 302 #define MYFLT float 303 #else 304 #define MYFLT double 305 #endif 306 #endif 307 %module csnd6 308 %{ 309 # include "sysdep.h" 310 # include "text.h" 311 # include <stdarg.h> 312 %} 313 #else 314 # include "sysdep.h" 315 # include "text.h" 316 # include <stdarg.h> 317 #endif 318 319 #ifdef __cplusplus 320 extern "C" { 321 #endif 322 323 /** 324 * ERROR DEFINITIONS 325 */ 326 327 typedef enum 328 { 329 /* Completed successfully. */ 330 CSOUND_SUCCESS = 0, 331 /* Unspecified failure. */ 332 CSOUND_ERROR = -1, 333 /* Failed during initialization. */ 334 CSOUND_INITIALIZATION = -2, 335 /* Failed during performance. */ 336 CSOUND_PERFORMANCE = -3, 337 /* Failed to allocate requested memory. */ 338 CSOUND_MEMORY = -4, 339 /* Termination requested by SIGINT or SIGTERM. */ 340 CSOUND_SIGNAL = -5 341 } CSOUND_STATUS; 342 343 /* Compilation or performance aborted, but not as a result of an error 344 (e.g. --help, or running an utility with -U). */ 345 #define CSOUND_EXITJMP_SUCCESS (256) 346 347 /** 348 * Flags for csoundInitialize(). 349 */ 350 351 #define CSOUNDINIT_NO_SIGNAL_HANDLER 1 352 #define CSOUNDINIT_NO_ATEXIT 2 353 354 /** 355 * Types for keyboard callbacks set in csoundRegisterKeyboardCallback() 356 */ 357 358 #define CSOUND_CALLBACK_KBD_EVENT (0x00000001U) 359 #define CSOUND_CALLBACK_KBD_TEXT (0x00000002U) 360 361 /** 362 * The following constants are used with csound->FileOpen2() and 363 * csound->ldmemfile2() to specify the format of a file that is being 364 * opened. This information is passed by Csound to a host's FileOpen 365 * callback and does not influence the opening operation in any other 366 * way. Conversion from Csound's TYP_XXX macros for audio formats to 367 * CSOUND_FILETYPES values can be done with csound->type2csfiletype(). 368 */ 369 typedef enum { 370 CSFTYPE_UNIFIED_CSD = 1, /* Unified Csound document */ 371 CSFTYPE_ORCHESTRA, /* the primary orc file (may be temporary) */ 372 CSFTYPE_SCORE, /* the primary sco file (may be temporary) 373 or any additional score opened by Cscore */ 374 CSFTYPE_ORC_INCLUDE, /* a file #included by the orchestra */ 375 CSFTYPE_SCO_INCLUDE, /* a file #included by the score */ 376 CSFTYPE_SCORE_OUT, /* used for score.srt, score.xtr, cscore.out */ 377 CSFTYPE_SCOT, /* Scot score input format */ 378 CSFTYPE_OPTIONS, /* for .csoundrc and -@ flag */ 379 CSFTYPE_EXTRACT_PARMS, /* extraction file specified by -x */ 380 381 /* audio file types that Csound can write (10-19) or read */ 382 CSFTYPE_RAW_AUDIO, 383 CSFTYPE_IRCAM, 384 CSFTYPE_AIFF, 385 CSFTYPE_AIFC, 386 CSFTYPE_WAVE, 387 CSFTYPE_AU, 388 CSFTYPE_SD2, 389 CSFTYPE_W64, 390 CSFTYPE_WAVEX, 391 CSFTYPE_FLAC, 392 CSFTYPE_CAF, 393 CSFTYPE_WVE, 394 CSFTYPE_OGG, 395 CSFTYPE_MPC2K, 396 CSFTYPE_RF64, 397 CSFTYPE_AVR, 398 CSFTYPE_HTK, 399 CSFTYPE_MAT4, 400 CSFTYPE_MAT5, 401 CSFTYPE_NIST, 402 CSFTYPE_PAF, 403 CSFTYPE_PVF, 404 CSFTYPE_SDS, 405 CSFTYPE_SVX, 406 CSFTYPE_VOC, 407 CSFTYPE_XI, 408 CSFTYPE_UNKNOWN_AUDIO, /* used when opening audio file for reading 409 or temp file written with <CsSampleB> */ 410 411 /* miscellaneous music formats */ 412 CSFTYPE_SOUNDFONT, 413 CSFTYPE_STD_MIDI, /* Standard MIDI file */ 414 CSFTYPE_MIDI_SYSEX, /* Raw MIDI codes, eg. SysEx dump */ 415 416 /* analysis formats */ 417 CSFTYPE_HETRO, 418 CSFTYPE_HETROT, 419 CSFTYPE_PVC, /* original PVOC format */ 420 CSFTYPE_PVCEX, /* PVOC-EX format */ 421 CSFTYPE_CVANAL, 422 CSFTYPE_LPC, 423 CSFTYPE_ATS, 424 CSFTYPE_LORIS, 425 CSFTYPE_SDIF, 426 CSFTYPE_HRTF, 427 428 /* Types for plugins and the files they read/write */ 429 CSFTYPE_VST_PLUGIN, 430 CSFTYPE_LADSPA_PLUGIN, 431 CSFTYPE_SNAPSHOT, 432 433 /* Special formats for Csound ftables or scanned synthesis 434 matrices with header info */ 435 CSFTYPE_FTABLES_TEXT, /* for ftsave and ftload */ 436 CSFTYPE_FTABLES_BINARY, /* for ftsave and ftload */ 437 CSFTYPE_XSCANU_MATRIX, /* for xscanu opcode */ 438 439 /* These are for raw lists of numbers without header info */ 440 CSFTYPE_FLOATS_TEXT, /* used by GEN23, GEN28, dumpk, readk */ 441 CSFTYPE_FLOATS_BINARY, /* used by dumpk, readk, etc. */ 442 CSFTYPE_INTEGER_TEXT, /* used by dumpk, readk, etc. */ 443 CSFTYPE_INTEGER_BINARY, /* used by dumpk, readk, etc. */ 444 445 /* image file formats */ 446 CSFTYPE_IMAGE_PNG, 447 448 /* For files that don't match any of the above */ 449 CSFTYPE_POSTSCRIPT, /* EPS format used by graphs */ 450 CSFTYPE_SCRIPT_TEXT, /* executable script files (eg. Python) */ 451 CSFTYPE_OTHER_TEXT, 452 CSFTYPE_OTHER_BINARY, 453 454 /* This should only be used internally by the original FileOpen() 455 API call or for temp files written with <CsFileB> */ 456 CSFTYPE_UNKNOWN = 0 457 } CSOUND_FILETYPES; 458 459 /* 460 * TYPE DEFINITIONS 461 */ 462 463 /* 464 * Forward declarations. 465 */ 466 467 typedef struct CSOUND_ CSOUND; 468 typedef struct windat_ WINDAT; 469 typedef struct xyindat_ XYINDAT; 470 471 472 /** 473 * csound configuration structure, mirrors part of 474 * OPARMS, uses more meaningful names 475 */ 476 477 typedef struct { 478 int debug_mode; /* debug mode, 0 or 1 */ 479 int buffer_frames; /* number of frames in in/out buffers */ 480 int hardware_buffer_frames; /* ibid. hardware */ 481 int displays; /* graph displays, 0 or 1 */ 482 int ascii_graphs; /* use ASCII graphs, 0 or 1 */ 483 int postscript_graphs; /* use postscript graphs, 0 or 1 */ 484 int message_level; /* message printout control */ 485 int tempo; /* tempo (sets Beatmode) */ 486 int ring_bell; /* bell, 0 or 1 */ 487 int use_cscore; /* use cscore for processing */ 488 int terminate_on_midi; /* terminate performance at the end 489 of midifile, 0 or 1 */ 490 int heartbeat; /* print heart beat, 0 or 1 */ 491 int defer_gen01_load ; /* defer GEN01 load, 0 or 1 */ 492 int midi_key; /* pfield to map midi key no */ 493 int midi_key_cps; /* pfield to map midi key no as cps */ 494 int midi_key_oct; /* pfield to map midi key no as oct */ 495 int midi_key_pch; /* pfield to map midi key no as pch */ 496 int midi_velocity; /* pfield to map midi velocity */ 497 int midi_velocity_amp; /* pfield to map midi velocity as amplitude */ 498 int no_default_paths; /* disable relative paths from files, 0 or 1 */ 499 int number_of_threads; /* number of threads for multicore performance */ 500 int syntax_check_only; /* do not compile, only check syntax */ 501 int csd_line_counts; /* csd line error reporting */ 502 int compute_weights; /* deprecated, kept for backwards comp. */ 503 int realtime_mode; /* use realtime priority mode, 0 or 1 */ 504 int sample_accurate; /* use sample-level score event accuracy */ 505 MYFLT sample_rate_override; /* overriding sample rate */ 506 MYFLT control_rate_override; /* overriding control rate */ 507 int nchnls_override; /* overriding number of out channels */ 508 int nchnls_i_override; /* overriding number of in channels */ 509 MYFLT e0dbfs_override; /* overriding 0dbfs */ 510 int daemon; /* daemon mode */ 511 int ksmps_override; /* ksmps override */ 512 int FFT_library; /* fft_lib */ 513 } CSOUND_PARAMS; 514 515 /** 516 * Device information 517 */ 518 typedef struct { 519 char device_name[64]; 520 char device_id[64]; 521 char rt_module[64]; 522 int max_nchnls; 523 int isOutput; 524 } CS_AUDIODEVICE; 525 526 typedef struct { 527 char device_name[64]; 528 char interface_name[64]; 529 char device_id[64]; 530 char midi_module[64]; 531 int isOutput; 532 } CS_MIDIDEVICE; 533 534 535 /** 536 * Real-time audio parameters structure 537 */ 538 typedef struct { 539 /** device name (NULL/empty: default) */ 540 char *devName; 541 /** device number (0-1023), 1024: default */ 542 int devNum; 543 /** buffer fragment size (-b) in sample frames */ 544 unsigned int bufSamp_SW; 545 /** total buffer size (-B) in sample frames */ 546 int bufSamp_HW; 547 /** number of channels */ 548 int nChannels; 549 /** sample format (AE_SHORT etc.) */ 550 int sampleFormat; 551 /** sample rate in Hz */ 552 float sampleRate; 553 } csRtAudioParams; 554 555 typedef struct RTCLOCK_S { 556 int_least64_t starttime_real; 557 int_least64_t starttime_CPU; 558 } RTCLOCK; 559 560 typedef struct { 561 char *opname; 562 char *outypes; 563 char *intypes; 564 int flags; 565 } opcodeListEntry; 566 567 typedef struct CsoundRandMTState_ { 568 int mti; 569 uint32_t mt[624]; 570 } CsoundRandMTState; 571 572 /* PVSDATEXT is a variation on PVSDAT used in 573 the pvs bus interface */ 574 typedef struct pvsdat_ext { 575 int32 N; 576 int sliding; /* Flag to indicate sliding case */ 577 int32 NB; 578 int32 overlap; 579 int32 winsize; 580 int wintype; 581 int32 format; 582 uint32 framecount; 583 float* frame; 584 } PVSDATEXT; 585 586 typedef struct ORCTOKEN { 587 int type; 588 char *lexeme; 589 int value; 590 double fvalue; 591 char *optype; 592 struct ORCTOKEN *next; 593 } ORCTOKEN; 594 595 typedef struct TREE { 596 int type; 597 ORCTOKEN *value; 598 int rate; 599 int len; 600 int line; 601 uint64_t locn; 602 struct TREE *left; 603 struct TREE *right; 604 struct TREE *next; 605 void *markup; // TEMPORARY - used by semantic checker to 606 // markup node adds OENTRY or synthetic var 607 // names to expression nodes should be moved 608 // to TYPE_TABLE 609 } TREE; 610 611 612 /** 613 * Constants used by the bus interface (csoundGetChannelPtr() etc.). 614 */ 615 typedef enum { 616 CSOUND_CONTROL_CHANNEL = 1, 617 CSOUND_AUDIO_CHANNEL = 2, 618 CSOUND_STRING_CHANNEL = 3, 619 CSOUND_PVS_CHANNEL = 4, 620 CSOUND_VAR_CHANNEL = 5, 621 622 CSOUND_CHANNEL_TYPE_MASK = 15, 623 624 CSOUND_INPUT_CHANNEL = 16, 625 CSOUND_OUTPUT_CHANNEL = 32 626 } controlChannelType; 627 628 typedef enum { 629 CSOUND_CONTROL_CHANNEL_NO_HINTS = 0, 630 CSOUND_CONTROL_CHANNEL_INT = 1, 631 CSOUND_CONTROL_CHANNEL_LIN = 2, 632 CSOUND_CONTROL_CHANNEL_EXP = 3 633 } controlChannelBehavior; 634 635 /** 636 * This structure holds the parameter hints for control channels 637 * 638 */ 639 typedef struct controlChannelHints_s { 640 controlChannelBehavior behav; 641 642 MYFLT dflt; 643 MYFLT min; 644 MYFLT max; 645 int x; 646 int y; 647 int width; 648 int height; 649 /** This member must be set explicitly to NULL if not used */ 650 char *attributes; 651 } controlChannelHints_t; 652 653 typedef struct controlChannelInfo_s { 654 char *name; 655 int type; 656 controlChannelHints_t hints; 657 } controlChannelInfo_t; 658 659 typedef void (*channelCallback_t)(CSOUND *csound, 660 const char *channelName, 661 void *channelValuePtr, 662 const void *channelType); 663 664 #ifndef CSOUND_CSDL_H 665 666 /** @defgroup INSTANTIATION Instantiation 667 * 668 * @{ */ 669 /** 670 * Initialise Csound library with specific flags. This function is called 671 * internally by csoundCreate(), so there is generally no need to use it 672 * explicitly unless you need to avoid default initilization that sets 673 * signal handlers and atexit() callbacks. 674 * Return value is zero on success, positive if initialisation was 675 * done already, and negative on error. 676 */ 677 PUBLIC int csoundInitialize(int flags); 678 679 /** 680 * Creates an instance of Csound. Returns an opaque pointer that 681 * must be passed to most Csound API functions. The hostData 682 * parameter can be NULL, or it can be a pointer to any sort of 683 * data; this pointer can be accessed from the Csound instance 684 * that is passed to callback routines. 685 */ 686 PUBLIC CSOUND *csoundCreate(void *hostData); 687 688 /** 689 * Destroys an instance of Csound. 690 */ 691 PUBLIC void csoundDestroy(CSOUND *); 692 693 /** 694 * Returns the version number times 1000 (5.00.0 = 5000). 695 */ 696 PUBLIC int csoundGetVersion(void); 697 698 /** 699 * Returns the API version number times 100 (1.00 = 100). 700 */ 701 PUBLIC int csoundGetAPIVersion(void); 702 /** @}*/ 703 704 /** @defgroup PERFORMANCE Performance 705 * 706 * @{ */ 707 /** 708 * Parse the given orchestra from an ASCII string into a TREE. 709 * This can be called during performance to parse new code. 710 */ 711 PUBLIC TREE *csoundParseOrc(CSOUND *csound, const char *str); 712 713 /** 714 * Compile the given TREE node into structs for Csound to use 715 * this can be called during performance to compile a new TREE 716 */ 717 PUBLIC int csoundCompileTree(CSOUND *csound, TREE *root); 718 719 /** 720 * Asynchronous version of csoundCompileTree() 721 */ 722 PUBLIC int csoundCompileTreeAsync(CSOUND *csound, TREE *root); 723 724 725 /** 726 * Free the resources associated with the TREE *tree 727 * This function should be called whenever the TREE was 728 * created with csoundParseOrc and memory can be deallocated. 729 **/ 730 PUBLIC void csoundDeleteTree(CSOUND *csound, TREE *tree); 731 732 /** 733 * Parse, and compile the given orchestra from an ASCII string, 734 * also evaluating any global space code (i-time only) 735 * this can be called during performance to compile a new orchestra. 736 * /code 737 * char *orc = "instr 1 \n a1 rand 0dbfs/4 \n out a1 \n"; 738 * csoundCompileOrc(csound, orc); 739 * /endcode 740 */ 741 PUBLIC int csoundCompileOrc(CSOUND *csound, const char *str); 742 743 /** 744 * Async version of csoundCompileOrc(). The code is parsed and 745 * compiled, then placed on a queue for 746 * asynchronous merge into the running engine, and evaluation. 747 * The function returns following parsing and compilation. 748 */ 749 PUBLIC int csoundCompileOrcAsync(CSOUND *csound, const char *str); 750 751 /** 752 * Parse and compile an orchestra given on an string, 753 * evaluating any global space code (i-time only). 754 * On SUCCESS it returns a value passed to the 755 * 'return' opcode in global space 756 * /code 757 * char *code = "i1 = 2 + 2 \n return i1 \n"; 758 * MYFLT retval = csoundEvalCode(csound, code); 759 * /endcode 760 */ 761 PUBLIC MYFLT csoundEvalCode(CSOUND *csound, const char *str); 762 763 /** 764 * Prepares an instance of Csound for Cscore 765 * processing outside of running an orchestra (i.e. "standalone Cscore"). 766 * It is an alternative to csoundCompile(), and 767 * csoundPerform*() and should not be used with these functions. 768 * You must call this function before using the interface in "cscore.h" 769 * when you do not wish to compile an orchestra. 770 * Pass it the already open FILE* pointers to the input and 771 * output score files. 772 * It returns CSOUND_SUCCESS on success and CSOUND_INITIALIZATION or other 773 * error code if it fails. 774 */ 775 PUBLIC int csoundInitializeCscore(CSOUND *, FILE *insco, FILE *outsco); 776 777 /** 778 * Read arguments, parse and compile an orchestra, read, process and 779 * load a score. 780 */ 781 PUBLIC int csoundCompileArgs(CSOUND *, int argc, const char **argv); 782 783 /** 784 * Prepares Csound for performance. Normally called after compiling 785 * a csd file or an orc file, in which case score preprocessing is 786 * performed and performance terminates when the score terminates. 787 * 788 * However, if called before compiling a csd file or an orc file, 789 * score preprocessing is not performed and "i" statements are dispatched 790 * as real-time events, the <CsOptions> tag is ignored, and performance 791 * continues indefinitely or until ended using the API. 792 */ 793 PUBLIC int csoundStart(CSOUND *csound); 794 795 /** 796 * Compiles Csound input files (such as an orchestra and score, or CSD) 797 * as directed by the supplied command-line arguments, 798 * but does not perform them. Returns a non-zero error code on failure. 799 * This function cannot be called during performance, and before a 800 * repeated call, csoundReset() needs to be called. 801 * In this (host-driven) mode, the sequence of calls should be as follows: 802 * /code 803 * csoundCompile(csound, argc, argv); 804 * while (!csoundPerformBuffer(csound)); 805 * csoundCleanup(csound); 806 * csoundReset(csound); 807 * /endcode 808 * Calls csoundStart() internally. 809 * Can only be called again after reset (see csoundReset()) 810 */ 811 PUBLIC int csoundCompile(CSOUND *, int argc, const char **argv); 812 813 /** 814 * Compiles a Csound input file (CSD, .csd file), but does not perform it. 815 * Returns a non-zero error code on failure. 816 * 817 * If csoundStart is called before csoundCompileCsd, the <CsOptions> 818 * element is ignored (but csoundSetOption can be called any number of 819 * times), the <CsScore> element is not pre-processed, but dispatched as 820 * real-time events; and performance continues indefinitely, or until 821 * ended by calling csoundStop or some other logic. In this "real-time" 822 * mode, the sequence of calls should be: 823 * 824 * \code 825 * 826 * csoundSetOption("-an_option"); 827 * csoundSetOption("-another_option"); 828 * csoundStart(csound); 829 * csoundCompileCsd(csound, csd_filename); 830 * while (1) { 831 * csoundPerformBuffer(csound); 832 * // Something to break out of the loop 833 * // when finished here... 834 * } 835 * csoundCleanup(csound); 836 * csoundReset(csound); 837 * 838 * \endcode 839 * 840 * NB: this function can be called repeatedly during performance to 841 * replace or add new instruments and events. 842 * 843 * But if csoundCompileCsd is called before csoundStart, the <CsOptions> 844 * element is used, the <CsScore> section is pre-processed and dispatched 845 * normally, and performance terminates when the score terminates, or 846 * csoundStop is called. In this "non-real-time" mode (which can still 847 * output real-time audio and handle real-time events), the sequence of 848 * calls should be: 849 * 850 * \code 851 * 852 * csoundCompileCsd(csound, csd_filename); 853 * csoundStart(csound); 854 * while (1) { 855 * int finished = csoundPerformBuffer(csound); 856 * if (finished) break; 857 * } 858 * csoundCleanup(csound); 859 * csoundReset(csound); 860 * 861 * \endcode 862 * 863 */ 864 PUBLIC int csoundCompileCsd(CSOUND *csound, const char *csd_filename); 865 866 /** 867 * Behaves the same way as csoundCompileCsd, except that the content 868 * of the CSD is read from the csd_text string rather than from a file. 869 * This is convenient when it is desirable to package the csd as part of 870 * an application or a multi-language piece. 871 */ 872 PUBLIC int csoundCompileCsdText(CSOUND *csound, const char *csd_text); 873 874 /** 875 * Senses input events and performs audio output until the end of score 876 * is reached (positive return value), an error occurs (negative return 877 * value), or performance is stopped by calling csoundStop() from another 878 * thread (zero return value). 879 * Note that csoundCompile() or csoundCompileOrc(), csoundReadScore(), 880 * csoundStart() must be called first. 881 * In the case of zero return value, csoundPerform() can be called again 882 * to continue the stopped performance. Otherwise, csoundReset() should be 883 * called to clean up after the finished or failed performance. 884 */ 885 PUBLIC int csoundPerform(CSOUND *); 886 887 /** 888 * Senses input events, and performs one control sample worth (ksmps) of 889 * audio output. 890 * Note that csoundCompile() or csoundCompileOrc(), csoundReadScore(), 891 * csoundStart() must be called first. 892 * Returns false during performance, and true when performance is finished. 893 * If called until it returns true, will perform an entire score. 894 * Enables external software to control the execution of Csound, 895 * and to synchronize performance with audio input and output. 896 */ 897 PUBLIC int csoundPerformKsmps(CSOUND *); 898 899 /** 900 * Performs Csound, sensing real-time and score events 901 * and processing one buffer's worth (-b frames) of interleaved audio. 902 * Note that csoundCompile must be called first, then call 903 * csoundGetOutputBuffer() and csoundGetInputBuffer() to get the pointer 904 * to csound's I/O buffers. 905 * Returns false during performance, and true when performance is finished. 906 */ 907 PUBLIC int csoundPerformBuffer(CSOUND *); 908 909 /** 910 * Stops a csoundPerform() running in another thread. Note that it is 911 * not guaranteed that csoundPerform() has already stopped when this 912 * function returns. 913 */ 914 PUBLIC void csoundStop(CSOUND *); 915 916 /** 917 * Prints information about the end of a performance, and closes audio 918 * and MIDI devices. 919 * Note: after calling csoundCleanup(), the operation of the perform 920 * functions is undefined. 921 */ 922 PUBLIC int csoundCleanup(CSOUND *); 923 924 /** 925 * Resets all internal memory and state in preparation for a new performance. 926 * Enables external software to run successive Csound performances 927 * without reloading Csound. Implies csoundCleanup(), unless already called. 928 */ 929 PUBLIC void csoundReset(CSOUND *); 930 931 /** @}*/ 932 /** @defgroup SERVER UDP server 933 * 934 * @{ */ 935 936 /** 937 * Starts the UDP server on a supplied port number 938 * returns CSOUND_SUCCESS if server has been started successfully, 939 * otherwise, CSOUND_ERROR. 940 */ 941 PUBLIC int csoundUDPServerStart(CSOUND *csound, unsigned int port); 942 943 /** returns the port number on which the server is running, or 944 * CSOUND_ERROR if the server is not running. 945 */ 946 PUBLIC int csoundUDPServerStatus(CSOUND *csound); 947 948 /** 949 * Closes the UDP server, returning CSOUND_SUCCESS if the 950 * running server was successfully closed, CSOUND_ERROR otherwise. 951 */ 952 PUBLIC int csoundUDPServerClose(CSOUND *csound); 953 954 /** 955 * Turns on the transmission of console messages to UDP on address addr 956 * port port. If mirror is one, the messages will continue to be 957 * sent to the usual destination (see csoundSetMessaggeCallback()) 958 * as well as to UDP. 959 * returns CSOUND_SUCCESS or CSOUND_ERROR if the UDP transmission 960 * could not be set up. 961 */ 962 PUBLIC int csoundUDPConsole(CSOUND *csound, const char *addr, 963 int port, int mirror); 964 965 /** 966 * Stop transmitting console messages via UDP 967 */ 968 PUBLIC void csoundStopUDPConsole(CSOUND *csound); 969 970 /** @}*/ 971 /** @defgroup ATTRIBUTES Attributes 972 * 973 * @{ */ 974 975 /** 976 * Returns the number of audio sample frames per second. 977 */ 978 PUBLIC MYFLT csoundGetSr(CSOUND *) ; 979 980 /** 981 * Returns the number of control samples per second. 982 */ 983 PUBLIC MYFLT csoundGetKr(CSOUND *); 984 985 /** 986 * Returns the number of audio sample frames per control sample. 987 */ 988 PUBLIC uint32_t csoundGetKsmps(CSOUND *); 989 990 /** 991 * Returns the number of audio output channels. Set through the nchnls 992 * header variable in the csd file. 993 */ 994 PUBLIC uint32_t csoundGetNchnls(CSOUND *); 995 996 /** 997 * Returns the number of audio input channels. Set through the 998 * nchnls_i header variable in the csd file. If this variable is 999 * not set, the value is taken from nchnls. 1000 */ 1001 PUBLIC uint32_t csoundGetNchnlsInput(CSOUND *csound); 1002 1003 /** 1004 * Returns the 0dBFS level of the spin/spout buffers. 1005 */ 1006 PUBLIC MYFLT csoundGet0dBFS(CSOUND *); 1007 1008 /** 1009 * Returns the A4 frequency reference 1010 */ 1011 PUBLIC MYFLT csoundGetA4(CSOUND *); 1012 1013 /** 1014 * Return the current performance time in samples 1015 */ 1016 PUBLIC int64_t csoundGetCurrentTimeSamples(CSOUND *csound); 1017 1018 /** 1019 * Return the size of MYFLT in bytes. 1020 */ 1021 PUBLIC int csoundGetSizeOfMYFLT(void); 1022 1023 /** 1024 * Returns host data. 1025 */ 1026 PUBLIC void *csoundGetHostData(CSOUND *); 1027 1028 /** 1029 * Sets host data. 1030 */ 1031 PUBLIC void csoundSetHostData(CSOUND *, void *hostData); 1032 1033 /** 1034 * Set a single csound option (flag). Returns CSOUND_SUCCESS on success. 1035 * NB: blank spaces are not allowed 1036 */ 1037 PUBLIC int csoundSetOption(CSOUND *csound, const char *option); 1038 1039 /** 1040 * Configure Csound with a given set of parameters defined in 1041 * the CSOUND_PARAMS structure. These parameters are the part of the 1042 * OPARMS struct that are configurable through command line flags. 1043 * The CSOUND_PARAMS structure can be obtained using csoundGetParams(). 1044 * These options should only be changed before performance has started. 1045 */ 1046 PUBLIC void csoundSetParams(CSOUND *csound, CSOUND_PARAMS *p); 1047 1048 /** 1049 * Get the current set of parameters from a CSOUND instance in 1050 * a CSOUND_PARAMS structure. See csoundSetParams(). 1051 */ 1052 PUBLIC void csoundGetParams(CSOUND *csound, CSOUND_PARAMS *p); 1053 1054 /** 1055 * Returns whether Csound is set to print debug messages sent through the 1056 * DebugMsg() internal API function. Anything different to 0 means true. 1057 */ 1058 PUBLIC int csoundGetDebug(CSOUND *); 1059 1060 /** 1061 * Sets whether Csound prints debug messages from the DebugMsg() internal 1062 * API function. Anything different to 0 means true. 1063 */ 1064 PUBLIC void csoundSetDebug(CSOUND *, int debug); 1065 1066 1067 /** @}*/ 1068 /** @defgroup FILEIO General Input/Output 1069 * Setting the device or filename name for Csound input and output. These 1070 * functions are used to set the input and output command line flags that 1071 * apply to both input and output of audio and MIDI. See command line flags 1072 * -o, -i, -M and -Q in the Csound Reference Manual. 1073 * @{ */ 1074 1075 /** 1076 * Returns the audio output name (-o). 1077 */ 1078 PUBLIC const char *csoundGetOutputName(CSOUND *); 1079 1080 /** 1081 * Returns the audio input name (-i). 1082 */ 1083 PUBLIC const char *csoundGetInputName(CSOUND *); 1084 1085 /** 1086 * Set output destination, type and format 1087 * type can be one of "wav","aiff", "au","raw", "paf", "svx", "nist", "voc", 1088 * "ircam","w64","mat4", "mat5", "pvf","xi", "htk","sds","avr","wavex","sd2", 1089 * "flac", "caf","wve","ogg","mpc2k","rf64", or NULL (use default or 1090 * realtime IO). 1091 * format can be one of "alaw", "schar", "uchar", "float", "double", "long", 1092 * "short", "ulaw", "24bit", "vorbis", or NULL (use default or realtime IO). 1093 * For RT audio, use device_id from CS_AUDIODEVICE for a given audio device. 1094 * 1095 */ 1096 PUBLIC void csoundSetOutput(CSOUND *csound, const char *name, 1097 const char *type, const char *format); 1098 1099 /** 1100 * Get output type and format. 1101 * type should have space for at least 5 chars excluding termination, 1102 * and format should have space for at least 7 chars. 1103 * On return, these will hold the current values for 1104 * these parameters. 1105 */ 1106 PUBLIC void csoundGetOutputFormat(CSOUND *csound,char *type, 1107 char *format); 1108 1109 /** 1110 * Set input source 1111 */ 1112 PUBLIC void csoundSetInput(CSOUND *csound, const char *name); 1113 1114 /** 1115 * Set MIDI input device name/number 1116 */ 1117 PUBLIC void csoundSetMIDIInput(CSOUND *csound, const char *name); 1118 1119 /** 1120 * Set MIDI file input name 1121 */ 1122 PUBLIC void csoundSetMIDIFileInput(CSOUND *csound, const char *name); 1123 1124 /** 1125 * Set MIDI output device name/number 1126 */ 1127 PUBLIC void csoundSetMIDIOutput(CSOUND *csound, const char *name); 1128 1129 /** 1130 * Set MIDI file utput name 1131 */ 1132 PUBLIC void csoundSetMIDIFileOutput(CSOUND *csound, const char *name); 1133 1134 #if !defined(SWIG) 1135 /** 1136 * Sets an external callback for receiving notices whenever Csound opens 1137 * a file. The callback is made after the file is successfully opened. 1138 * The following information is passed to the callback: 1139 * char* pathname of the file; either full or relative to current dir 1140 * int a file type code from the enumeration CSOUND_FILETYPES 1141 * int 1 if Csound is writing the file, 0 if reading 1142 * int 1 if a temporary file that Csound will delete; 0 if not 1143 * 1144 * Pass NULL to disable the callback. 1145 * This callback is retained after a csoundReset() call. 1146 */ 1147 PUBLIC void csoundSetFileOpenCallback(CSOUND *p, 1148 void (*func)(CSOUND*, const char*, 1149 int, int, int)); 1150 #endif 1151 1152 /** @}*/ 1153 /** @defgroup RTAUDIOIO Realtime Audio I/O 1154 * 1155 * @{ */ 1156 1157 /** 1158 * Sets the current RT audio module 1159 */ 1160 PUBLIC void csoundSetRTAudioModule(CSOUND *csound, const char *module); 1161 1162 /** 1163 * retrieves a module name and type ("audio" or "midi") given a 1164 * number Modules are added to list as csound loads them returns 1165 * CSOUND_SUCCESS on success and CSOUND_ERROR if module number 1166 * was not found 1167 * 1168 * \code 1169 * char *name, *type; 1170 * int n = 0; 1171 * while(!csoundGetModule(csound, n++, &name, &type)) 1172 * printf("Module %d: %s (%s) \n", n, name, type); 1173 * \endcode 1174 */ 1175 PUBLIC int csoundGetModule(CSOUND *csound, int number, 1176 char **name, char **type); 1177 1178 /** 1179 * Returns the number of samples in Csound's input buffer. 1180 */ 1181 PUBLIC long csoundGetInputBufferSize(CSOUND *); 1182 1183 /** 1184 * Returns the number of samples in Csound's output buffer. 1185 */ 1186 PUBLIC long csoundGetOutputBufferSize(CSOUND *); 1187 1188 /** 1189 * Returns the address of the Csound audio input buffer. 1190 * Enables external software to write audio into Csound before calling 1191 * csoundPerformBuffer. 1192 */ 1193 PUBLIC MYFLT *csoundGetInputBuffer(CSOUND *); 1194 1195 /** 1196 * Returns the address of the Csound audio output buffer. 1197 * Enables external software to read audio from Csound after calling 1198 * csoundPerformBuffer. 1199 */ 1200 PUBLIC MYFLT *csoundGetOutputBuffer(CSOUND *); 1201 1202 /** 1203 * Returns the address of the Csound audio input working buffer (spin). 1204 * Enables external software to write audio into Csound before calling 1205 * csoundPerformKsmps. 1206 */ 1207 PUBLIC MYFLT *csoundGetSpin(CSOUND *); 1208 1209 /** 1210 * Clears the input buffer (spin). 1211 */ 1212 PUBLIC void csoundClearSpin(CSOUND *); 1213 1214 /** 1215 * Adds the indicated sample into the audio input working buffer (spin); 1216 * this only ever makes sense before calling csoundPerformKsmps(). 1217 * The frame and channel must be in bounds relative to ksmps and nchnls. 1218 * NB: the spin buffer needs to be cleared at every k-cycle by calling 1219 * csoundClearSpinBuffer(). 1220 */ 1221 PUBLIC void csoundAddSpinSample(CSOUND *csound, 1222 int frame, int channel, MYFLT sample); 1223 1224 /** 1225 * Sets the audio input working buffer (spin) to the indicated sample 1226 * this only ever makes sense before calling csoundPerformKsmps(). 1227 * The frame and channel must be in bounds relative to ksmps and nchnls. 1228 */ 1229 PUBLIC void csoundSetSpinSample(CSOUND *csound, 1230 int frame, int channel, MYFLT sample); 1231 1232 /** 1233 * Returns the address of the Csound audio output working buffer (spout). 1234 * Enables external software to read audio from Csound after calling 1235 * csoundPerformKsmps. 1236 */ 1237 PUBLIC MYFLT *csoundGetSpout(CSOUND *csound); 1238 1239 /** 1240 * Returns the indicated sample from the Csound audio output 1241 * working buffer (spout); only ever makes sense after calling 1242 * csoundPerformKsmps(). The frame and channel must be in bounds 1243 * relative to ksmps and nchnls. 1244 */ 1245 PUBLIC MYFLT csoundGetSpoutSample(CSOUND *csound, int frame, int channel); 1246 1247 /** 1248 * Return pointer to user data pointer for real time audio input. 1249 */ 1250 PUBLIC void **csoundGetRtRecordUserData(CSOUND *); 1251 1252 /** 1253 * Return pointer to user data pointer for real time audio output. 1254 */ 1255 PUBLIC void **csoundGetRtPlayUserData(CSOUND *); 1256 1257 /** 1258 * Calling this function with a non-zero 'state' value between 1259 * csoundCreate() and the start of performance will disable all default 1260 * handling of sound I/O by the Csound library, allowing the host 1261 * application to use the spin/spout/input/output buffers directly. 1262 * For applications using spin/spout, bufSize should be set to 0. 1263 * If 'bufSize' is greater than zero, the buffer size (-b) in frames will be 1264 * set to the integer multiple of ksmps that is nearest to the value 1265 * specified. 1266 */ 1267 PUBLIC void csoundSetHostImplementedAudioIO(CSOUND *, 1268 int state, int bufSize); 1269 1270 1271 /** 1272 * This function can be called to obtain a list of available 1273 * input or output audio devices. If list is NULL, the function 1274 * will only return the number of devices (isOutput=1 for out 1275 * devices, 0 for in devices). 1276 * If list is non-NULL, then it should contain enough memory for 1277 * one CS_AUDIODEVICE structure per device. 1278 * Hosts will typically call this function twice: first to obtain 1279 * a number of devices, then, after allocating space for each 1280 * device information structure, pass an array of CS_AUDIODEVICE 1281 * structs to be filled: 1282 * 1283 * \code 1284 * int i,n = csoundGetAudioDevList(csound,NULL,1); 1285 * CS_AUDIODEVICE *devs = (CS_AUDIODEVICE *) 1286 * malloc(n*sizeof(CS_AUDIODEVICE)); 1287 * csoundGetAudioDevList(csound,devs,1); 1288 * for(i=0; i < n; i++) 1289 * csound->Message(csound, " %d: %s (%s)\n", 1290 * i, devs[i].device_id, devs[i].device_name); 1291 * free(devs); 1292 * \endcode 1293 */ 1294 PUBLIC int csoundGetAudioDevList(CSOUND *csound, 1295 CS_AUDIODEVICE *list, int isOutput); 1296 1297 /** 1298 * Sets a function to be called by Csound for opening real-time 1299 * audio playback. 1300 */ 1301 PUBLIC void 1302 csoundSetPlayopenCallback(CSOUND *, 1303 int (*playopen__)(CSOUND *, 1304 const csRtAudioParams *parm)); 1305 1306 /** 1307 * Sets a function to be called by Csound for performing real-time 1308 * audio playback. 1309 */ 1310 PUBLIC void csoundSetRtplayCallback(CSOUND *, 1311 void (*rtplay__)(CSOUND *, 1312 const MYFLT *outBuf, 1313 int nbytes)); 1314 1315 /** 1316 * Sets a function to be called by Csound for opening real-time 1317 * audio recording. 1318 */ 1319 PUBLIC void csoundSetRecopenCallback(CSOUND *, 1320 int (*recopen_)(CSOUND *, 1321 const csRtAudioParams *parm)); 1322 1323 /** 1324 * Sets a function to be called by Csound for performing real-time 1325 * audio recording. 1326 */ 1327 PUBLIC void csoundSetRtrecordCallback(CSOUND *, 1328 int (*rtrecord__)(CSOUND *, 1329 MYFLT *inBuf, 1330 int nbytes)); 1331 1332 /** 1333 * Sets a function to be called by Csound for closing real-time 1334 * audio playback and recording. 1335 */ 1336 PUBLIC void csoundSetRtcloseCallback(CSOUND *, void (*rtclose__)(CSOUND *)); 1337 1338 /** 1339 * Sets a function that is called to obtain a list of audio devices. 1340 * This should be set by rtaudio modules and should not be set by hosts. 1341 * (See csoundGetAudioDevList()) 1342 */ 1343 PUBLIC void csoundSetAudioDeviceListCallback(CSOUND *csound, 1344 int (*audiodevlist__)(CSOUND *, 1345 CS_AUDIODEVICE *list, 1346 int isOutput)); 1347 1348 /** @}*/ 1349 /** @defgroup RTMIDI Realtime Midi I/O 1350 * 1351 * @{ */ 1352 1353 /** 1354 * Sets the current MIDI IO module 1355 */ 1356 PUBLIC void csoundSetMIDIModule(CSOUND *csound, const char *module); 1357 1358 /** 1359 * call this function with state 1 if the host is implementing 1360 * MIDI via the callbacks below. 1361 */ 1362 PUBLIC void csoundSetHostImplementedMIDIIO(CSOUND *csound, 1363 int state); 1364 1365 /** 1366 * This function can be called to obtain a list of available 1367 * input or output midi devices. If list is NULL, the function 1368 * will only return the number of devices (isOutput=1 for out 1369 * devices, 0 for in devices). 1370 * If list is non-NULL, then it should contain enough memory for 1371 * one CS_MIDIDEVICE structure per device. 1372 * Hosts will typically call this function twice: first to obtain 1373 * a number of devices, then, after allocating space for each 1374 * device information structure, pass an array of CS_MIDIDEVICE 1375 * structs to be filled. (see also csoundGetAudioDevList()) 1376 */ 1377 PUBLIC int csoundGetMIDIDevList(CSOUND *csound, 1378 CS_MIDIDEVICE *list, int isOutput); 1379 1380 /** 1381 * Sets callback for opening real time MIDI input. 1382 */ 1383 PUBLIC void csoundSetExternalMidiInOpenCallback(CSOUND *, 1384 int (*func)(CSOUND *, 1385 void **userData, 1386 const char *devName)); 1387 1388 /** 1389 * Sets callback for reading from real time MIDI input. 1390 */ 1391 PUBLIC void csoundSetExternalMidiReadCallback(CSOUND *, 1392 int (*func)(CSOUND *, 1393 void *userData, 1394 unsigned char *buf, 1395 int nBytes)); 1396 1397 /** 1398 * Sets callback for closing real time MIDI input. 1399 */ 1400 PUBLIC void csoundSetExternalMidiInCloseCallback(CSOUND *, 1401 int (*func)(CSOUND *, 1402 void *userData)); 1403 1404 /** 1405 * Sets callback for opening real time MIDI output. 1406 */ 1407 PUBLIC void csoundSetExternalMidiOutOpenCallback(CSOUND *, 1408 int (*func)(CSOUND *, 1409 void **userData, 1410 const char *devName)); 1411 1412 /** 1413 * Sets callback for writing to real time MIDI output. 1414 */ 1415 PUBLIC void csoundSetExternalMidiWriteCallback(CSOUND *, 1416 int (*func)(CSOUND *, 1417 void *userData, 1418 const unsigned char *buf, 1419 int nBytes)); 1420 1421 /** 1422 * Sets callback for closing real time MIDI output. 1423 */ 1424 PUBLIC void csoundSetExternalMidiOutCloseCallback(CSOUND *, 1425 int (*func)(CSOUND *, 1426 void *userData)); 1427 1428 /** 1429 * Sets callback for converting MIDI error codes to strings. 1430 */ 1431 PUBLIC void csoundSetExternalMidiErrorStringCallback(CSOUND *, 1432 const char *(*func)(int)); 1433 1434 1435 /** 1436 * Sets a function that is called to obtain a list of MIDI devices. 1437 * This should be set by IO plugins, and should not be used by hosts. 1438 * (See csoundGetMIDIDevList()) 1439 */ 1440 PUBLIC void csoundSetMIDIDeviceListCallback(CSOUND *csound, 1441 int (*mididevlist__)(CSOUND *, 1442 CS_MIDIDEVICE *list, 1443 int isOutput)); 1444 1445 /** @}*/ 1446 /** @defgroup SCOREHANDLING Score Handling 1447 * 1448 * @{ */ 1449 1450 /** 1451 * Read, preprocess, and load a score from an ASCII string 1452 * It can be called repeatedly, with the new score events 1453 * being added to the currently scheduled ones. 1454 */ 1455 PUBLIC int csoundReadScore(CSOUND *csound, const char *str); 1456 1457 /** 1458 * Asynchronous version of csoundReadScore(). 1459 */ 1460 PUBLIC void csoundReadScoreAsync(CSOUND *csound, const char *str); 1461 1462 /** 1463 * Returns the current score time in seconds 1464 * since the beginning of performance. 1465 */ 1466 PUBLIC double csoundGetScoreTime(CSOUND *); 1467 1468 /** 1469 * Sets whether Csound score events are performed or not, independently 1470 * of real-time MIDI events (see csoundSetScorePending()). 1471 */ 1472 PUBLIC int csoundIsScorePending(CSOUND *); 1473 1474 /** 1475 * Sets whether Csound score events are performed or not (real-time 1476 * events will continue to be performed). Can be used by external software, 1477 * such as a VST host, to turn off performance of score events (while 1478 * continuing to perform real-time events), for example to 1479 * mute a Csound score while working on other tracks of a piece, or 1480 * to play the Csound instruments live. 1481 */ 1482 PUBLIC void csoundSetScorePending(CSOUND *, int pending); 1483 1484 /** 1485 * Returns the score time beginning at which score events will 1486 * actually immediately be performed (see csoundSetScoreOffsetSeconds()). 1487 */ 1488 PUBLIC MYFLT csoundGetScoreOffsetSeconds(CSOUND *); 1489 1490 /** 1491 * Csound score events prior to the specified time are not performed, and 1492 * performance begins immediately at the specified time (real-time events 1493 * will continue to be performed as they are received). 1494 * Can be used by external software, such as a VST host, 1495 * to begin score performance midway through a Csound score, 1496 * for example to repeat a loop in a sequencer, or to synchronize 1497 * other events with the Csound score. 1498 */ 1499 PUBLIC void csoundSetScoreOffsetSeconds(CSOUND *, MYFLT time); 1500 1501 /** 1502 * Rewinds a compiled Csound score to the time specified with 1503 * csoundSetScoreOffsetSeconds(). 1504 */ 1505 PUBLIC void csoundRewindScore(CSOUND *); 1506 1507 /** 1508 * Sets an external callback for Cscore processing. 1509 * Pass NULL to reset to the internal cscore() function 1510 * (which does nothing). 1511 * This callback is retained after a csoundReset() call. 1512 */ 1513 PUBLIC void csoundSetCscoreCallback(CSOUND *, 1514 void (*cscoreCallback_)(CSOUND *)); 1515 1516 /** 1517 * Sorts score file 'inFile' and writes the result to 'outFile'. 1518 * The Csound instance should be initialised 1519 * before calling this function, and csoundReset() should be called 1520 * after sorting the score to clean up. On success, zero is returned. 1521 */ 1522 PUBLIC int csoundScoreSort(CSOUND *, FILE *inFile, FILE *outFile); 1523 1524 /** 1525 * Extracts from 'inFile', controlled by 'extractFile', and writes 1526 * the result to 'outFile'. The Csound instance should be initialised 1527 * before calling this function, and csoundReset() 1528 * should be called after score extraction to clean up. 1529 * The return value is zero on success. 1530 */ 1531 PUBLIC int csoundScoreExtract(CSOUND *, 1532 FILE *inFile, FILE *outFile, FILE *extractFile); 1533 1534 /** @}*/ 1535 /** @defgroup MESSAGES Messages and Text 1536 * 1537 * @{ */ 1538 1539 /** 1540 * Displays an informational message. 1541 */ 1542 PUBLIC CS_PRINTF2 void csoundMessage(CSOUND *, const char *format, ...); 1543 1544 /** 1545 * Print message with special attributes (see msg_attr.h for the list of 1546 * available attributes). With attr=0, csoundMessageS() is identical to 1547 * csoundMessage(). 1548 */ 1549 PUBLIC CS_PRINTF3 void csoundMessageS(CSOUND *, 1550 int attr, const char *format, ...); 1551 1552 PUBLIC void csoundMessageV(CSOUND *, 1553 int attr, const char *format, va_list args); 1554 1555 PUBLIC void csoundSetDefaultMessageCallback(void (*csoundMessageCallback_)( 1556 CSOUND *, 1557 int attr, 1558 const char *format, 1559 va_list valist)); 1560 1561 /** 1562 * Sets a function to be called by Csound to print an informational message. 1563 * This callback is never called on --realtime mode 1564 */ 1565 PUBLIC void csoundSetMessageCallback(CSOUND *, 1566 void (*csoundMessageCallback_)(CSOUND *, 1567 int attr, 1568 const char *format, 1569 va_list valist)); 1570 1571 /** 1572 * Sets an alternative function to be called by Csound to print an 1573 * informational message, using a less granular signature. 1574 * This callback can be set for --realtime mode 1575 */ 1576 PUBLIC void csoundSetMessageStringCallback(CSOUND *csound, 1577 void (*csoundMessageStrCallback)(CSOUND *csound, 1578 int attr, 1579 const char *str)); 1580 1581 /** 1582 * Returns the Csound message level (from 0 to 231). 1583 */ 1584 PUBLIC int csoundGetMessageLevel(CSOUND *); 1585 1586 /** 1587 * Sets the Csound message level (from 0 to 231). 1588 */ 1589 PUBLIC void csoundSetMessageLevel(CSOUND *, int messageLevel); 1590 1591 /** 1592 * Creates a buffer for storing messages printed by Csound. 1593 * Should be called after creating a Csound instance andthe buffer 1594 * can be freed by calling csoundDestroyMessageBuffer() before 1595 * deleting the Csound instance. You will generally want to call 1596 * csoundCleanup() to make sure the last messages are flushed to 1597 * the message buffer before destroying Csound. 1598 * If 'toStdOut' is non-zero, the messages are also printed to 1599 * stdout and stderr (depending on the type of the message), 1600 * in addition to being stored in the buffer. 1601 * Using the message buffer ties up the internal message callback, so 1602 * csoundSetMessageCallback should not be called after creating the 1603 * message buffer. 1604 */ 1605 PUBLIC void csoundCreateMessageBuffer(CSOUND *csound, int toStdOut); 1606 1607 /** 1608 * Returns the first message from the buffer. 1609 */ 1610 PUBLIC const char* csoundGetFirstMessage(CSOUND *csound); 1611 1612 /** 1613 * Returns the attribute parameter (see msg_attr.h) of the first message 1614 * in the buffer. 1615 */ 1616 PUBLIC int csoundGetFirstMessageAttr(CSOUND *csound); 1617 1618 /** 1619 * Removes the first message from the buffer. 1620 */ 1621 PUBLIC void csoundPopFirstMessage(CSOUND *csound); 1622 1623 /** 1624 * Returns the number of pending messages in the buffer. 1625 */ 1626 PUBLIC int csoundGetMessageCnt(CSOUND *csound); 1627 1628 /** 1629 * Releases all memory used by the message buffer. 1630 */ 1631 void PUBLIC csoundDestroyMessageBuffer(CSOUND *csound); 1632 1633 /** @}*/ 1634 /** @defgroup CONTROLEVENTS Channels, Control and Events 1635 * 1636 * @{ */ 1637 1638 /** 1639 * Stores a pointer to the specified channel of the bus in *p, 1640 * creating the channel first if it does not exist yet. 1641 * 'type' must be the bitwise OR of exactly one of the following values, 1642 * CSOUND_CONTROL_CHANNEL 1643 * control data (one MYFLT value) 1644 * CSOUND_AUDIO_CHANNEL 1645 * audio data (csoundGetKsmps(csound) MYFLT values) 1646 * CSOUND_STRING_CHANNEL 1647 * string data (MYFLT values with enough space to store 1648 * csoundGetChannelDatasize() characters, including the 1649 * NULL character at the end of the string) 1650 * and at least one of these: 1651 * CSOUND_INPUT_CHANNEL 1652 * CSOUND_OUTPUT_CHANNEL 1653 * If the channel already exists, it must match the data type 1654 * (control, audio, or string), however, the input/output bits are 1655 * OR'd with the new value. Note that audio and string channels 1656 * can only be created after calling csoundCompile(), because the 1657 * storage size is not known until then. 1658 1659 * Return value is zero on success, or a negative error code, 1660 * CSOUND_MEMORY there is not enough memory for allocating the channel 1661 * CSOUND_ERROR the specified name or type is invalid 1662 * or, if a channel with the same name but incompatible type 1663 * already exists, the type of the existing channel. In the case 1664 * of any non-zero return value, *p is set to NULL. 1665 * Note: to find out the type of a channel without actually 1666 * creating or changing it, set 'type' to zero, so that the return 1667 * value will be either the type of the channel, or CSOUND_ERROR 1668 * if it does not exist. 1669 * 1670 * Operations on **p are not thread-safe by default. The host is required 1671 * to take care of threadsafety by 1672 * 1) with control channels use __atomic_load() or 1673 * __atomic_store() gcc atomic builtins to get or set a channel, 1674 * if available. 1675 * 2) For string and audio channels (and controls if option 1 is not 1676 * available), retrieve the channel lock with csoundGetChannelLock() 1677 * and use csoundSpinLock() and csoundSpinUnLock() to protect access 1678 * to **p. 1679 * See Top/threadsafe.c in the Csound library sources for 1680 * examples. Optionally, use the channel get/set functions 1681 * provided below, which are threadsafe by default. 1682 */ 1683 PUBLIC int csoundGetChannelPtr(CSOUND *, 1684 MYFLT **p, const char *name, int type); 1685 1686 /** 1687 * Returns a list of allocated channels in *lst. A controlChannelInfo_t 1688 * structure contains the channel characteristics. 1689 * The return value is the number of channels, which may be zero if there 1690 * are none, or CSOUND_MEMORY if there is not enough memory for allocating 1691 * the list. In the case of no channels or an error, *lst is set to NULL. 1692 * Notes: the caller is responsible for freeing the list returned in *lst 1693 * with csoundDeleteChannelList(). The name pointers may become invalid 1694 * after calling csoundReset(). 1695 */ 1696 PUBLIC int csoundListChannels(CSOUND *, controlChannelInfo_t **lst); 1697 1698 /** 1699 * Releases a channel list previously returned by csoundListChannels(). 1700 */ 1701 PUBLIC void csoundDeleteChannelList(CSOUND *, controlChannelInfo_t *lst); 1702 1703 /** 1704 * Set parameters hints for a control channel. These hints have no internal 1705 * function but can be used by front ends to construct GUIs or to constrain 1706 * values. See the controlChannelHints_t structure for details. 1707 * Returns zero on success, or a non-zero error code on failure: 1708 * CSOUND_ERROR: the channel does not exist, is not a control channel, 1709 * or the specified parameters are invalid 1710 * CSOUND_MEMORY: could not allocate memory 1711 */ 1712 PUBLIC int csoundSetControlChannelHints(CSOUND *, const char *name, 1713 controlChannelHints_t hints); 1714 1715 /** 1716 * Returns special parameters (assuming there are any) of a control channel, 1717 * previously set with csoundSetControlChannelHints() or the chnparams 1718 * opcode. 1719 * If the channel exists, is a control channel, the channel hints 1720 * are stored in the preallocated controlChannelHints_t structure. The 1721 * attributes member of the structure will be allocated inside this function 1722 * so it is necessary to free it explicitly in the host. 1723 * 1724 * The return value is zero if the channel exists and is a control 1725 * channel, otherwise, an error code is returned. 1726 */ 1727 PUBLIC int csoundGetControlChannelHints(CSOUND *, const char *name, 1728 controlChannelHints_t *hints); 1729 1730 /** 1731 * Recovers a pointer to a lock for the specified channel called 'name'. 1732 * The returned lock can be locked/unlocked with the csoundSpinLock() 1733 * and csoundSpinUnLock() functions. 1734 * @returns the address of the lock or NULL if the channel does not exist 1735 */ 1736 PUBLIC int *csoundGetChannelLock(CSOUND *, const char *name); 1737 1738 /** 1739 * retrieves the value of control channel identified by *name. 1740 * If the err argument is not NULL, the error (or success) code 1741 * finding or accessing the channel is stored in it. 1742 */ 1743 PUBLIC MYFLT csoundGetControlChannel(CSOUND *csound, const char *name, 1744 int *err); 1745 1746 /** 1747 * sets the value of control channel identified by *name 1748 */ 1749 PUBLIC void csoundSetControlChannel(CSOUND *csound, 1750 const char *name, MYFLT val); 1751 1752 /** 1753 * copies the audio channel identified by *name into array 1754 * *samples which should contain enough memory for ksmps MYFLTs 1755 */ 1756 PUBLIC void csoundGetAudioChannel(CSOUND *csound, 1757 const char *name, MYFLT *samples); 1758 1759 /** 1760 * sets the audio channel identified by *name with data from array 1761 * *samples which should contain at least ksmps MYFLTs 1762 */ 1763 PUBLIC void csoundSetAudioChannel(CSOUND *csound, 1764 const char *name, MYFLT *samples); 1765 1766 /** 1767 * copies the string channel identified by *name into *string 1768 * which should contain enough memory for the string 1769 * (see csoundGetChannelDatasize() below) 1770 */ 1771 PUBLIC void csoundGetStringChannel(CSOUND *csound, 1772 const char *name, char *string); 1773 1774 /** 1775 * sets the string channel identified by *name with *string 1776 */ 1777 PUBLIC void csoundSetStringChannel(CSOUND *csound, 1778 const char *name, char *string); 1779 1780 /** 1781 * returns the size of data stored in a channel; for string channels 1782 * this might change if the channel space gets reallocated 1783 * Since string variables use dynamic memory allocation in Csound6, 1784 * this function can be called to get the space required for 1785 * csoundGetStringChannel() 1786 */ 1787 PUBLIC int csoundGetChannelDatasize(CSOUND *csound, const char *name); 1788 1789 /** Sets the function which will be called whenever the invalue opcode 1790 * is used. */ 1791 PUBLIC void 1792 csoundSetInputChannelCallback(CSOUND *csound, 1793 channelCallback_t inputChannelCalback); 1794 1795 /** Sets the function which will be called whenever the outvalue opcode 1796 * is used. */ 1797 PUBLIC void 1798 csoundSetOutputChannelCallback(CSOUND *csound, 1799 channelCallback_t outputChannelCalback); 1800 1801 /** 1802 * Sends a PVSDATEX fin to the pvsin opcode (f-rate) for channel 'name'. 1803 * Returns zero on success, CSOUND_ERROR if the index is invalid or 1804 * fsig framesizes are incompatible. 1805 * CSOUND_MEMORY if there is not enough memory to extend the bus. 1806 */ 1807 PUBLIC int csoundSetPvsChannel(CSOUND *, const PVSDATEXT *fin, 1808 const char *name); 1809 1810 /** 1811 * Receives a PVSDAT fout from the pvsout opcode (f-rate) at channel 'name' 1812 * Returns zero on success, CSOUND_ERROR if the index is invalid or 1813 * if fsig framesizes are incompatible. 1814 * CSOUND_MEMORY if there is not enough memory to extend the bus 1815 */ 1816 PUBLIC int csoundGetPvsChannel(CSOUND *csound, PVSDATEXT *fout, 1817 const char *name); 1818 1819 /** 1820 * Send a new score event. 'type' is the score event type ('a', 'i', 'q', 1821 * 'f', or 'e'). 1822 * 'numFields' is the size of the pFields array. 'pFields' is an array of 1823 * floats with all the pfields for this event, starting with the p1 value 1824 * specified in pFields[0]. 1825 */ 1826 PUBLIC int csoundScoreEvent(CSOUND *, 1827 char type, const MYFLT *pFields, long numFields); 1828 1829 /** 1830 * Asynchronous version of csoundScoreEvent(). 1831 */ 1832 PUBLIC void csoundScoreEventAsync(CSOUND *, 1833 char type, const MYFLT *pFields, long numFields); 1834 1835 /** 1836 * Like csoundScoreEvent(), this function inserts a score event, but 1837 * at absolute time with respect to the start of performance, or from an 1838 * offset set with time_ofs 1839 */ 1840 PUBLIC int csoundScoreEventAbsolute(CSOUND *, 1841 char type, const MYFLT *pfields, long numFields, double time_ofs); 1842 1843 /** 1844 * Asynchronous version of csoundScoreEventAbsolute(). 1845 */ 1846 PUBLIC void csoundScoreEventAbsoluteAsync(CSOUND *, 1847 char type, const MYFLT *pfields, long numFields, double time_ofs); 1848 /** 1849 * Input a NULL-terminated string (as if from a console), 1850 * used for line events. 1851 */ 1852 PUBLIC void csoundInputMessage(CSOUND *, const char *message); 1853 1854 /** 1855 * Asynchronous version of csoundInputMessage(). 1856 */ 1857 PUBLIC void csoundInputMessageAsync(CSOUND *, const char *message); 1858 1859 /** 1860 * Kills off one or more running instances of an instrument identified 1861 * by instr (number) or instrName (name). If instrName is NULL, the 1862 * instrument number is used. 1863 * Mode is a sum of the following values: 1864 * 0,1,2: kill all instances (1), oldest only (1), or newest (2) 1865 * 4: only turnoff notes with exactly matching (fractional) instr number 1866 * 8: only turnoff notes with indefinite duration (p3 < 0 or MIDI) 1867 * allow_release, if non-zero, the killed instances are allowed to release. 1868 */ 1869 PUBLIC int csoundKillInstance(CSOUND *csound, MYFLT instr, 1870 char *instrName, int mode, int allow_release); 1871 1872 1873 /** 1874 * Register a function to be called once in every control period 1875 * by sensevents(). Any number of functions may be registered, 1876 * and will be called in the order of registration. 1877 * The callback function takes two arguments: the Csound instance 1878 * pointer, and the userData pointer as passed to this function. 1879 * This facility can be used to ensure a function is called synchronously 1880 * before every csound control buffer processing. It is important 1881 * to make sure no blocking operations are performed in the callback. 1882 * The callbacks are cleared on csoundCleanup(). 1883 * Returns zero on success. 1884 */ 1885 PUBLIC int csoundRegisterSenseEventCallback(CSOUND *, 1886 void (*func)(CSOUND *, void *), 1887 void *userData); 1888 1889 /** 1890 * Set the ASCII code of the most recent key pressed. 1891 * This value is used by the 'sensekey' opcode if a callback 1892 * for returning keyboard events is not set (see 1893 * csoundRegisterKeyboardCallback()). 1894 */ 1895 PUBLIC void csoundKeyPress(CSOUND *, char c); 1896 1897 /** 1898 * Registers general purpose callback functions that will be called to query 1899 * keyboard events. These callbacks are called on every control period by 1900 * the sensekey opcode. 1901 * The callback is preserved on csoundReset(), and multiple 1902 * callbacks may be set and will be called in reverse order of 1903 * registration. If the same function is set again, it is only moved 1904 * in the list of callbacks so that it will be called first, and the 1905 * user data and type mask parameters are updated. 'typeMask' can be the 1906 * bitwise OR of callback types for which the function should be called, 1907 * or zero for all types. 1908 * Returns zero on success, CSOUND_ERROR if the specified function 1909 * pointer or type mask is invalid, and CSOUND_MEMORY if there is not 1910 * enough memory. 1911 * 1912 * The callback function takes the following arguments: 1913 * void *userData 1914 * the "user data" pointer, as specified when setting the callback 1915 * void *p 1916 * data pointer, depending on the callback type 1917 * unsigned int type 1918 * callback type, can be one of the following (more may be added in 1919 * future versions of Csound): 1920 * CSOUND_CALLBACK_KBD_EVENT 1921 * CSOUND_CALLBACK_KBD_TEXT 1922 * called by the sensekey opcode to fetch key codes. The data 1923 * pointer is a pointer to a single value of type 'int', for 1924 * returning the key code, which can be in the range 1 to 65535, 1925 * or 0 if there is no keyboard event. 1926 * For CSOUND_CALLBACK_KBD_EVENT, both key press and release 1927 * events should be returned (with 65536 (0x10000) added to the 1928 * key code in the latter case) as unshifted ASCII codes. 1929 * CSOUND_CALLBACK_KBD_TEXT expects key press events only as the 1930 * actual text that is typed. 1931 * The return value should be zero on success, negative on error, and 1932 * positive if the callback was ignored (for example because the type is 1933 * not known). 1934 */ 1935 PUBLIC int csoundRegisterKeyboardCallback(CSOUND *, 1936 int (*func)(void *userData, void *p, 1937 unsigned int type), 1938 void *userData, unsigned int type); 1939 1940 /** 1941 * Removes a callback previously set with csoundRegisterKeyboardCallback(). 1942 */ 1943 PUBLIC void csoundRemoveKeyboardCallback(CSOUND *csound, 1944 int (*func)(void *, void *, unsigned int)); 1945 1946 /** @}*/ 1947 /** @defgroup TABLE Tables 1948 * 1949 * @{ */ 1950 /** 1951 * Returns the length of a function table (not including the guard point), 1952 * or -1 if the table does not exist. 1953 */ 1954 PUBLIC int csoundTableLength(CSOUND *, int table); 1955 1956 /** 1957 * Returns the value of a slot in a function table. 1958 * The table number and index are assumed to be valid. 1959 */ 1960 PUBLIC MYFLT csoundTableGet(CSOUND *, int table, int index); 1961 1962 /** 1963 * Sets the value of a slot in a function table. 1964 * The table number and index are assumed to be valid. 1965 */ 1966 PUBLIC void csoundTableSet(CSOUND *, int table, int index, MYFLT value); 1967 1968 1969 /** 1970 * Copy the contents of a function table into a supplied array *dest 1971 * The table number is assumed to be valid, and the destination needs to 1972 * have sufficient space to receive all the function table contents. 1973 */ 1974 PUBLIC void csoundTableCopyOut(CSOUND *csound, int table, MYFLT *dest); 1975 1976 /** 1977 * Asynchronous version of csoundTableCopyOut() 1978 */ 1979 PUBLIC void csoundTableCopyOutAsync(CSOUND *csound, int table, MYFLT *dest); 1980 /** 1981 * Copy the contents of an array *src into a given function table 1982 * The table number is assumed to be valid, and the table needs to 1983 * have sufficient space to receive all the array contents. 1984 */ 1985 PUBLIC void csoundTableCopyIn(CSOUND *csound, int table, MYFLT *src); 1986 1987 /** 1988 * Asynchronous version of csoundTableCopyIn() 1989 */ 1990 PUBLIC void csoundTableCopyInAsync(CSOUND *csound, int table, MYFLT *src); 1991 1992 /** 1993 * Stores pointer to function table 'tableNum' in *tablePtr, 1994 * and returns the table length (not including the guard point). 1995 * If the table does not exist, *tablePtr is set to NULL and 1996 * -1 is returned. 1997 */ 1998 PUBLIC int csoundGetTable(CSOUND *, MYFLT **tablePtr, int tableNum); 1999 2000 /** 2001 * Stores pointer to the arguments used to generate 2002 * function table 'tableNum' in *argsPtr, 2003 * and returns the number of arguments used. 2004 * If the table does not exist, *argsPtr is set to NULL and 2005 * -1 is returned. 2006 * NB: the argument list starts with the GEN number and is followed by 2007 * its parameters. eg. f 1 0 1024 10 1 0.5 yields the list {10.0,1.0,0.5} 2008 */ 2009 PUBLIC int csoundGetTableArgs(CSOUND *csound, MYFLT **argsPtr, int tableNum); 2010 2011 /** 2012 * Checks if a given GEN number num is a named GEN 2013 * if so, it returns the string length (excluding terminating NULL char) 2014 * Otherwise it returns 0. 2015 */ 2016 PUBLIC int csoundIsNamedGEN(CSOUND *csound, int num); 2017 2018 /** 2019 * Gets the GEN name from a number num, if this is a named GEN 2020 * The final parameter is the max len of the string (excluding termination) 2021 */ 2022 PUBLIC void csoundGetNamedGEN(CSOUND *csound, int num, char *name, int len); 2023 2024 /** @}*/ 2025 /** @defgroup TABLEDISPLAY Function table display 2026 * 2027 * @{ */ 2028 /** 2029 * Tells Csound whether external graphic table display is supported. 2030 * Returns the previously set value (initially zero). 2031 */ 2032 PUBLIC int csoundSetIsGraphable(CSOUND *, int isGraphable); 2033 2034 /** 2035 * Called by external software to set Csound's MakeGraph function. 2036 */ 2037 PUBLIC void csoundSetMakeGraphCallback(CSOUND *, 2038 void (*makeGraphCallback_)(CSOUND *, 2039 WINDAT *windat, 2040 const char *name)); 2041 2042 /** 2043 * Called by external software to set Csound's DrawGraph function. 2044 */ 2045 PUBLIC void csoundSetDrawGraphCallback(CSOUND *, 2046 void (*drawGraphCallback_)(CSOUND *, 2047 WINDAT *windat)); 2048 2049 /** 2050 * Called by external software to set Csound's KillGraph function. 2051 */ 2052 PUBLIC void csoundSetKillGraphCallback(CSOUND *, 2053 void (*killGraphCallback_)(CSOUND *, 2054 WINDAT *windat)); 2055 2056 /** 2057 * Called by external software to set Csound's ExitGraph function. 2058 */ 2059 PUBLIC void csoundSetExitGraphCallback(CSOUND *, 2060 int (*exitGraphCallback_)(CSOUND *)); 2061 2062 /** @}*/ 2063 /** @defgroup OPCODES Opcodes 2064 * 2065 * @{ */ 2066 2067 /** 2068 * Finds the list of named gens 2069 */ 2070 PUBLIC void *csoundGetNamedGens(CSOUND *); 2071 2072 /** 2073 * Gets an alphabetically sorted list of all opcodes. 2074 * Should be called after externals are loaded by csoundCompile(). 2075 * Returns the number of opcodes, or a negative error code on failure. 2076 * Make sure to call csoundDisposeOpcodeList() when done with the list. 2077 */ 2078 PUBLIC int csoundNewOpcodeList(CSOUND *, opcodeListEntry **opcodelist); 2079 2080 /** 2081 * Releases an opcode list. 2082 */ 2083 PUBLIC void csoundDisposeOpcodeList(CSOUND *, opcodeListEntry *opcodelist); 2084 2085 /** 2086 * Appends an opcode implemented by external software 2087 * to Csound's internal opcode list. 2088 * The opcode list is extended by one slot, 2089 * and the parameters are copied into the new slot. 2090 * Returns zero on success. 2091 */ 2092 PUBLIC int csoundAppendOpcode(CSOUND *, const char *opname, 2093 int dsblksiz, int flags, int thread, 2094 const char *outypes, const char *intypes, 2095 int (*iopadr)(CSOUND *, void *), 2096 int (*kopadr)(CSOUND *, void *), 2097 int (*aopadr)(CSOUND *, void *)); 2098 2099 /** @}*/ 2100 /** @defgroup THREADING Threading and concurrency 2101 * 2102 * @{ */ 2103 2104 /** 2105 * Called by external software to set a function for checking system 2106 * events, yielding cpu time for coopertative multitasking, etc. 2107 * This function is optional. It is often used as a way to 'turn off' 2108 * Csound, allowing it to exit gracefully. In addition, some operations 2109 * like utility analysis routines are not reentrant and you should use 2110 * this function to do any kind of updating during the operation. 2111 * Returns an 'OK to continue' boolean. 2112 */ 2113 PUBLIC void csoundSetYieldCallback(CSOUND *, int (*yieldCallback_)(CSOUND *)); 2114 2115 /** 2116 * Creates and starts a new thread of execution. 2117 * Returns an opaque pointer that represents the thread on success, 2118 * or NULL for failure. 2119 * The userdata pointer is passed to the thread routine. 2120 */ 2121 PUBLIC void *csoundCreateThread(uintptr_t (*threadRoutine)(void *), 2122 void *userdata); 2123 2124 /** 2125 * Returns the ID of the currently executing thread, 2126 * or NULL for failure. 2127 * 2128 * NOTE: The return value can be used as a pointer 2129 * to a thread object, but it should not be compared 2130 * as a pointer. The pointed to values should be compared, 2131 * and the user must free the pointer after use. 2132 */ 2133 PUBLIC void *csoundGetCurrentThreadId(void); 2134 2135 /** 2136 * Waits until the indicated thread's routine has finished. 2137 * Returns the value returned by the thread routine. 2138 */ 2139 PUBLIC uintptr_t csoundJoinThread(void *thread); 2140 /** 2141 * Creates and returns a monitor object, or NULL if not successful. 2142 * The object is initially in signaled (notified) state. 2143 */ 2144 PUBLIC void *csoundCreateThreadLock(void); 2145 2146 /** 2147 * Waits on the indicated monitor object for the indicated period. 2148 * The function returns either when the monitor object is notified, 2149 * or when the period has elapsed, whichever is sooner; in the first case, 2150 * zero is returned. 2151 * If 'milliseconds' is zero and the object is not notified, the function 2152 * will return immediately with a non-zero status. 2153 */ 2154 PUBLIC int csoundWaitThreadLock(void *lock, size_t milliseconds); 2155 2156 /** 2157 * Waits on the indicated monitor object until it is notified. 2158 * This function is similar to csoundWaitThreadLock() with an infinite 2159 * wait time, but may be more efficient. 2160 */ 2161 PUBLIC void csoundWaitThreadLockNoTimeout(void *lock); 2162 2163 /** 2164 * Notifies the indicated monitor object. 2165 */ 2166 PUBLIC void csoundNotifyThreadLock(void *lock); 2167 2168 /** 2169 * Destroys the indicated monitor object. 2170 */ 2171 PUBLIC void csoundDestroyThreadLock(void *lock); 2172 2173 /** 2174 * Creates and returns a mutex object, or NULL if not successful. 2175 * Mutexes can be faster than the more general purpose monitor objects 2176 * returned by csoundCreateThreadLock() on some platforms, and can also 2177 * be recursive, but the result of unlocking a mutex that is owned by 2178 * another thread or is not locked is undefined. 2179 * If 'isRecursive' is non-zero, the mutex can be re-locked multiple 2180 * times by the same thread, requiring an equal number of unlock calls; 2181 * otherwise, attempting to re-lock the mutex results in undefined 2182 * behavior. 2183 * Note: the handles returned by csoundCreateThreadLock() and 2184 * csoundCreateMutex() are not compatible. 2185 */ 2186 PUBLIC void *csoundCreateMutex(int isRecursive); 2187 2188 /** 2189 * Acquires the indicated mutex object; if it is already in use by 2190 * another thread, the function waits until the mutex is released by 2191 * the other thread. 2192 */ 2193 PUBLIC void csoundLockMutex(void *mutex_); 2194 2195 /** 2196 * Acquires the indicated mutex object and returns zero, unless it is 2197 * already in use by another thread, in which case a non-zero value is 2198 * returned immediately, rather than waiting until the mutex becomes 2199 * available. 2200 * Note: this function may be unimplemented on Windows. 2201 */ 2202 PUBLIC int csoundLockMutexNoWait(void *mutex_); 2203 2204 /** 2205 * Releases the indicated mutex object, which should be owned by 2206 * the current thread, otherwise the operation of this function is 2207 * undefined. A recursive mutex needs to be unlocked as many times 2208 * as it was locked previously. 2209 */ 2210 PUBLIC void csoundUnlockMutex(void *mutex_); 2211 2212 /** 2213 * Destroys the indicated mutex object. Destroying a mutex that 2214 * is currently owned by a thread results in undefined behavior. 2215 */ 2216 PUBLIC void csoundDestroyMutex(void *mutex_); 2217 2218 2219 /** 2220 * Create a Thread Barrier. Max value parameter should be equal to 2221 * number of child threads using the barrier plus one for the 2222 * master thread */ 2223 2224 PUBLIC void *csoundCreateBarrier(unsigned int max); 2225 2226 /** 2227 * Destroy a Thread Barrier. 2228 */ 2229 PUBLIC int csoundDestroyBarrier(void *barrier); 2230 2231 /** 2232 * Wait on the thread barrier. 2233 */ 2234 PUBLIC int csoundWaitBarrier(void *barrier); 2235 2236 2237 /** Creates a conditional variable */ 2238 PUBLIC void* csoundCreateCondVar(); 2239 2240 /** Waits up on a conditional variable and mutex */ 2241 PUBLIC void csoundCondWait(void* condVar, void* mutex); 2242 2243 /** Signals a conditional variable */ 2244 PUBLIC void csoundCondSignal(void* condVar); 2245 2246 /** 2247 * Waits for at least the specified number of milliseconds, 2248 * yielding the CPU to other threads. 2249 */ 2250 PUBLIC void csoundSleep(size_t milliseconds); 2251 2252 /** 2253 * If the spinlock is not locked, lock it and return; 2254 * if is is locked, wait until it is unlocked, then lock it and return. 2255 * Uses atomic compare and swap operations that are safe across processors 2256 * and safe for out of order operations, 2257 * and which are more efficient than operating system locks. 2258 * Use spinlocks to protect access to shared data, especially in functions 2259 * that do little more than read or write such data, for example: 2260 * 2261 * @code 2262 * static spin_lock_t lock = SPINLOCK_INIT; 2263 * csoundSpinLockInit(&lock); 2264 * void write(size_t frames, int* signal) 2265 * { 2266 * csoundSpinLock(&lock); 2267 * for (size_t frame = 0; i < frames; frame++) { 2268 * global_buffer[frame] += signal[frame]; 2269 * } 2270 * csoundSpinUnlock(&lock); 2271 * } 2272 * @endcode 2273 */ 2274 PUBLIC int csoundSpinLockInit(spin_lock_t *spinlock); 2275 2276 /** 2277 * Locks the spinlock 2278 */ 2279 PUBLIC void csoundSpinLock(spin_lock_t *spinlock); 2280 2281 /** 2282 * Tries the lock, returns CSOUND_SUCCESS if lock could be acquired, 2283 CSOUND_ERROR, otherwise. 2284 */ 2285 PUBLIC int csoundSpinTryLock(spin_lock_t *spinlock); 2286 2287 /** 2288 * Unlocks the spinlock 2289 */ 2290 PUBLIC void csoundSpinUnLock(spin_lock_t *spinlock); 2291 2292 2293 /** @}*/ 2294 /** @defgroup MISCELLANEOUS Miscellaneous functions 2295 * 2296 * @{ */ 2297 2298 /** 2299 * Runs an external command with the arguments specified in 'argv'. 2300 * argv[0] is the name of the program to execute (if not a full path 2301 * file name, it is searched in the directories defined by the PATH 2302 * environment variable). The list of arguments should be terminated 2303 * by a NULL pointer. 2304 * If 'noWait' is zero, the function waits until the external program 2305 * finishes, otherwise it returns immediately. In the first case, a 2306 * non-negative return value is the exit status of the command (0 to 2307 * 255), otherwise it is the PID of the newly created process. 2308 * On error, a negative value is returned. 2309 */ 2310 PUBLIC long csoundRunCommand(const char * const *argv, int noWait); 2311 2312 /** 2313 * Initialise a timer structure. 2314 */ 2315 PUBLIC void csoundInitTimerStruct(RTCLOCK *); 2316 2317 /** 2318 * Return the elapsed real time (in seconds) since the specified timer 2319 * structure was initialised. 2320 */ 2321 PUBLIC double csoundGetRealTime(RTCLOCK *); 2322 2323 /** 2324 * Return the elapsed CPU time (in seconds) since the specified timer 2325 * structure was initialised. 2326 */ 2327 PUBLIC double csoundGetCPUTime(RTCLOCK *); 2328 2329 /** 2330 * Return a 32-bit unsigned integer to be used as seed from current time. 2331 */ 2332 PUBLIC uint32_t csoundGetRandomSeedFromTime(void); 2333 2334 /** 2335 * Set language to 'lang_code' (lang_code can be for example 2336 * CSLANGUAGE_ENGLISH_UK or CSLANGUAGE_FRENCH or many others, 2337 * see n_getstr.h for the list of languages). This affects all 2338 * Csound instances running in the address space of the current 2339 * process. The special language code CSLANGUAGE_DEFAULT can be 2340 * used to disable translation of messages and free all memory 2341 * allocated by a previous call to csoundSetLanguage(). 2342 * csoundSetLanguage() loads all files for the selected language 2343 * from the directory specified by the CSSTRNGS environment 2344 * variable. 2345 */ 2346 PUBLIC void csoundSetLanguage(cslanguage_t lang_code); 2347 2348 /** 2349 * Get pointer to the value of environment variable 'name', searching 2350 * in this order: local environment of 'csound' (if not NULL), variables 2351 * set with csoundSetGlobalEnv(), and system environment variables. 2352 * If 'csound' is not NULL, should be called after csoundCompile(). 2353 * Return value is NULL if the variable is not set. 2354 */ 2355 PUBLIC const char *csoundGetEnv(CSOUND *csound, const char *name); 2356 2357 /** 2358 * Set the global value of environment variable 'name' to 'value', 2359 * or delete variable if 'value' is NULL. 2360 * It is not safe to call this function while any Csound instances 2361 * are active. 2362 * Returns zero on success. 2363 */ 2364 PUBLIC int csoundSetGlobalEnv(const char *name, const char *value); 2365 2366 /** 2367 * Allocate nbytes bytes of memory that can be accessed later by calling 2368 * csoundQueryGlobalVariable() with the specified name; the space is 2369 * cleared to zero. 2370 * Returns CSOUND_SUCCESS on success, CSOUND_ERROR in case of invalid 2371 * parameters (zero nbytes, invalid or already used name), or 2372 * CSOUND_MEMORY if there is not enough memory. 2373 */ 2374 PUBLIC int csoundCreateGlobalVariable(CSOUND *, 2375 const char *name, size_t nbytes); 2376 2377 /** 2378 * Get pointer to space allocated with the name "name". 2379 * Returns NULL if the specified name is not defined. 2380 */ 2381 PUBLIC void *csoundQueryGlobalVariable(CSOUND *, const char *name); 2382 2383 /** 2384 * This function is the same as csoundQueryGlobalVariable(), except the 2385 * variable is assumed to exist and no error checking is done. 2386 * Faster, but may crash or return an invalid pointer if 'name' is 2387 * not defined. 2388 */ 2389 PUBLIC void *csoundQueryGlobalVariableNoCheck(CSOUND *, const char *name); 2390 2391 /** 2392 * Free memory allocated for "name" and remove "name" from the database. 2393 * Return value is CSOUND_SUCCESS on success, or CSOUND_ERROR if the name is 2394 * not defined. 2395 */ 2396 PUBLIC int csoundDestroyGlobalVariable(CSOUND *, const char *name); 2397 2398 /** 2399 * Run utility with the specified name and command line arguments. 2400 * Should be called after loading utility plugins. 2401 * Use csoundReset() to clean up after calling this function. 2402 * Returns zero if the utility was run successfully. 2403 */ 2404 PUBLIC int csoundRunUtility(CSOUND *, const char *name, 2405 int argc, char **argv); 2406 2407 /** 2408 * Returns a NULL terminated list of registered utility names. 2409 * The caller is responsible for freeing the returned array with 2410 * csoundDeleteUtilityList(), however, the names should not be 2411 * changed or freed. 2412 * The return value may be NULL in case of an error. 2413 */ 2414 PUBLIC char **csoundListUtilities(CSOUND *); 2415 2416 /** 2417 * Releases an utility list previously returned by csoundListUtilities(). 2418 */ 2419 PUBLIC void csoundDeleteUtilityList(CSOUND *, char **lst); 2420 2421 /** 2422 * Get utility description. 2423 * Returns NULL if the utility was not found, or it has no description, 2424 * or an error occured. 2425 */ 2426 PUBLIC const char *csoundGetUtilityDescription(CSOUND *, 2427 const char *utilName); 2428 2429 /** 2430 * Simple linear congruential random number generator: 2431 * (*seedVal) = (*seedVal) * 742938285 % 2147483647 2432 * the initial value of *seedVal must be in the range 1 to 2147483646. 2433 * Returns the next number from the pseudo-random sequence, 2434 * in the range 1 to 2147483646. 2435 */ 2436 PUBLIC int csoundRand31(int *seedVal); 2437 2438 /** 2439 * Initialise Mersenne Twister (MT19937) random number generator, 2440 * using 'keyLength' unsigned 32 bit values from 'initKey' as seed. 2441 * If the array is NULL, the length parameter is used for seeding. 2442 */ 2443 PUBLIC void csoundSeedRandMT(CsoundRandMTState *p, 2444 const uint32_t *initKey, uint32_t keyLength); 2445 2446 /** 2447 * Returns next random number from MT19937 generator. 2448 * The PRNG must be initialised first by calling csoundSeedRandMT(). 2449 */ 2450 PUBLIC uint32_t csoundRandMT(CsoundRandMTState *p); 2451 2452 #endif /* !CSOUND_CSDL_H */ 2453 2454 /* typedefs, macros, and interface functions for configuration variables */ 2455 #include "cfgvar.h" 2456 /* message attribute definitions for csoundMessageS() and csoundMessageV() */ 2457 #include "msg_attr.h" 2458 /* macro definitions for Csound release, and API version */ 2459 #include "version.h" 2460 2461 /** 2462 * Create circular buffer with numelem number of elements. The 2463 * element's size is set from elemsize. It should be used like: 2464 *@code 2465 * void *rb = csoundCreateCircularBuffer(csound, 1024, sizeof(MYFLT)); 2466 *@endcode 2467 */ 2468 PUBLIC void *csoundCreateCircularBuffer(CSOUND *csound, 2469 int numelem, int elemsize); 2470 2471 /** 2472 * Read from circular buffer 2473 * @param csound This value is currently ignored. 2474 * @param circular_buffer pointer to an existing circular buffer 2475 * @param out preallocated buffer with at least items number of elements, where 2476 * buffer contents will be read into 2477 * @param items number of samples to be read 2478 * @returns the actual number of items read (0 <= n <= items) 2479 */ 2480 PUBLIC int csoundReadCircularBuffer(CSOUND *csound, void *circular_buffer, 2481 void *out, int items); 2482 2483 /** 2484 * Read from circular buffer without removing them from the buffer. 2485 * @param circular_buffer pointer to an existing circular buffer 2486 * @param out preallocated buffer with at least items number of elements, where 2487 * buffer contents will be read into 2488 * @param items number of samples to be read 2489 * @returns the actual number of items read (0 <= n <= items) 2490 */ 2491 PUBLIC int csoundPeekCircularBuffer(CSOUND *csound, void *circular_buffer, 2492 void *out, int items); 2493 2494 /** 2495 * Write to circular buffer 2496 * @param csound This value is currently ignored. 2497 * @param p pointer to an existing circular buffer 2498 * @param inp buffer with at least items number of elements to be written into 2499 * circular buffer 2500 * @param items number of samples to write 2501 * @returns the actual number of items written (0 <= n <= items) 2502 */ 2503 PUBLIC int csoundWriteCircularBuffer(CSOUND *csound, void *p, 2504 const void *inp, int items); 2505 /** 2506 * Empty circular buffer of any remaining data. This function should only be 2507 * used if there is no reader actively getting data from the buffer. 2508 * @param csound This value is currently ignored. 2509 * @param p pointer to an existing circular buffer 2510 */ 2511 PUBLIC void csoundFlushCircularBuffer(CSOUND *csound, void *p); 2512 2513 /** 2514 * Free circular buffer 2515 */ 2516 PUBLIC void csoundDestroyCircularBuffer(CSOUND *csound, void *circularbuffer); 2517 2518 /** 2519 * Platform-independent function to load a shared library. 2520 */ 2521 PUBLIC int csoundOpenLibrary(void **library, const char *libraryPath); 2522 2523 /** 2524 * Platform-independent function to unload a shared library. 2525 */ 2526 PUBLIC int csoundCloseLibrary(void *library); 2527 2528 /** 2529 * Platform-independent function to get a symbol address in a shared library. 2530 */ 2531 PUBLIC void *csoundGetLibrarySymbol(void *library, const char *symbolName); 2532 2533 2534 /** @}*/ 2535 2536 #ifdef SWIGPYTHON 2537 csoundGetInstance(int64_t obj)2538 PUBLIC CSOUND *csoundGetInstance(int64_t obj){ return (CSOUND *)obj; } 2539 2540 #endif 2541 2542 2543 #ifdef SOME_FINE_DAY /* these functions are now deprecated */ 2544 2545 /** 2546 * Returns a pointer to the requested interface, if available, in the 2547 * interface argument, and its version number, in the version argument. 2548 * Returns 0 for success. 2549 */ 2550 2551 PUBLIC int csoundQueryInterface(const char *name, 2552 void **iface, int *version); 2553 2554 2555 /** 2556 * Control values are specified by a 'channelName' string. 2557 * Note that the 'invalue' & 'outvalue' channels can be specified by 2558 * either a string or a number. If a number is specified, it will be 2559 * converted to a string before making the callbacks to the external 2560 * software. 2561 */ 2562 2563 /** 2564 * Called by external software to set a function for Csound to 2565 * fetch input control values. The 'invalue' opcodes will 2566 * directly call this function. If 'channelName' starts with a 2567 * '$', then 'invalue' opcode is expecting a C string, to be copied 2568 * to 'value', with maximum size csoundGetChannelDatasize(). 2569 */ 2570 PUBLIC void csoundSetInputValueCallback(CSOUND *, 2571 void (*inputValueCalback_)(CSOUND *, 2572 const char *channelName, 2573 MYFLT *value)); 2574 2575 /** 2576 * Called by external software to set a function for Csound to 2577 * send output control values. The 'outvalue' opcodes will 2578 * directly call this function. If 'channelName' starts with a 2579 * '$', then the 'outvalue' opcode is sending a string appended 2580 * to channelName in the format: "$channelName$stringOutput". 2581 * and 'value' will be the index number into 'channelName' where 2582 * the stringOutput begins. 2583 */ 2584 PUBLIC void csoundSetOutputValueCallback(CSOUND *, 2585 void (*outputValueCalback_)(CSOUND *, 2586 const char *channelName, 2587 MYFLT value)); 2588 2589 /** 2590 * Sets callback function to be called by the opcodes 'chnsend' and 2591 * 'chnrecv'. Should be called before csoundCompile(). 2592 * The callback function takes the following arguments: 2593 * CSOUND *csound 2594 * Csound instance pointer 2595 * const char *channelName 2596 * the channel name 2597 * MYFLT *channelValuePtr 2598 * pointer to the channel value. Control channels are a single MYFLT 2599 * value, while audio channels are an array of csoundGetKsmps(csound) 2600 * MYFLT values. In the case of string channels, the pointer should be 2601 * cast to char *, and points to a buffer of 2602 * csoundGetChannelDatasize() bytes 2603 * int channelType 2604 * bitwise OR of the channel type (CSOUND_CONTROL_CHANNEL, 2605 * CSOUND_AUDIO_CHANNEL, or CSOUND_STRING_CHANNEL; use 2606 * channelType & CSOUND_CHANNEL_TYPE_MASK to extract the channel 2607 * type), and either CSOUND_INPUT_CHANNEL or CSOUND_OUTPUT_CHANNEL 2608 * to indicate the direction of the data transfer 2609 * The callback is not preserved on csoundReset(). 2610 */ 2611 PUBLIC void csoundSetChannelIOCallback(CSOUND *, 2612 CsoundChannelIOCallback_t func); 2613 2614 /** 2615 * Senses input events, and performs one control sample worth (ksmps) of 2616 * audio output. 2617 * Note that csoundCompile() or csoundCompileOrc(), 2618 * csoundReadScore(), csoundStart() must be called first. 2619 * Performs audio whether or not the Csound score has finished. 2620 * Enables external software to control the execution of Csound, 2621 * and to synchronize performance with audio input and output. 2622 */ 2623 PUBLIC int csoundPerformKsmpsAbsolute(CSOUND *); 2624 #endif 2625 2626 2627 #ifdef __cplusplus 2628 } 2629 #endif 2630 2631 #endif /* CSOUND_H */ 2632