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_UNUSED, 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 * Sets an opcodedir override for csoundCreate() 681 */ 682 PUBLIC void csoundSetOpcodedir(const char *s); 683 684 /** 685 * Creates an instance of Csound. Returns an opaque pointer that 686 * must be passed to most Csound API functions. The hostData 687 * parameter can be NULL, or it can be a pointer to any sort of 688 * data; this pointer can be accessed from the Csound instance 689 * that is passed to callback routines. 690 */ 691 PUBLIC CSOUND *csoundCreate(void *hostData); 692 693 /** 694 * Loads all plugins from a given directory 695 */ 696 PUBLIC int csoundLoadPlugins(CSOUND *csound, const char *dir); 697 698 /** 699 * Destroys an instance of Csound. 700 */ 701 PUBLIC void csoundDestroy(CSOUND *); 702 703 /** 704 * Returns the version number times 1000 (5.00.0 = 5000). 705 */ 706 PUBLIC int csoundGetVersion(void); 707 708 /** 709 * Returns the API version number times 100 (1.00 = 100). 710 */ 711 PUBLIC int csoundGetAPIVersion(void); 712 713 714 /** @}*/ 715 716 /** @defgroup PERFORMANCE Performance 717 * 718 * @{ */ 719 /** 720 * Parse the given orchestra from an ASCII string into a TREE. 721 * This can be called during performance to parse new code. 722 */ 723 PUBLIC TREE *csoundParseOrc(CSOUND *csound, const char *str); 724 725 /** 726 * Compile the given TREE node into structs for Csound to use 727 * this can be called during performance to compile a new TREE 728 */ 729 PUBLIC int csoundCompileTree(CSOUND *csound, TREE *root); 730 731 /** 732 * Asynchronous version of csoundCompileTree() 733 */ 734 PUBLIC int csoundCompileTreeAsync(CSOUND *csound, TREE *root); 735 736 737 /** 738 * Free the resources associated with the TREE *tree 739 * This function should be called whenever the TREE was 740 * created with csoundParseOrc and memory can be deallocated. 741 **/ 742 PUBLIC void csoundDeleteTree(CSOUND *csound, TREE *tree); 743 744 /** 745 * Parse, and compile the given orchestra from an ASCII string, 746 * also evaluating any global space code (i-time only) 747 * this can be called during performance to compile a new orchestra. 748 * /code 749 * char *orc = "instr 1 \n a1 rand 0dbfs/4 \n out a1 \n"; 750 * csoundCompileOrc(csound, orc); 751 * /endcode 752 */ 753 PUBLIC int csoundCompileOrc(CSOUND *csound, const char *str); 754 755 /** 756 * Async version of csoundCompileOrc(). The code is parsed and 757 * compiled, then placed on a queue for 758 * asynchronous merge into the running engine, and evaluation. 759 * The function returns following parsing and compilation. 760 */ 761 PUBLIC int csoundCompileOrcAsync(CSOUND *csound, const char *str); 762 763 /** 764 * Parse and compile an orchestra given on an string, 765 * evaluating any global space code (i-time only). 766 * On SUCCESS it returns a value passed to the 767 * 'return' opcode in global space 768 * /code 769 * char *code = "i1 = 2 + 2 \n return i1 \n"; 770 * MYFLT retval = csoundEvalCode(csound, code); 771 * /endcode 772 */ 773 PUBLIC MYFLT csoundEvalCode(CSOUND *csound, const char *str); 774 775 /** 776 * Prepares an instance of Csound for Cscore 777 * processing outside of running an orchestra (i.e. "standalone Cscore"). 778 * It is an alternative to csoundCompile(), and 779 * csoundPerform*() and should not be used with these functions. 780 * You must call this function before using the interface in "cscore.h" 781 * when you do not wish to compile an orchestra. 782 * Pass it the already open FILE* pointers to the input and 783 * output score files. 784 * It returns CSOUND_SUCCESS on success and CSOUND_INITIALIZATION or other 785 * error code if it fails. 786 */ 787 PUBLIC int csoundInitializeCscore(CSOUND *, FILE *insco, FILE *outsco); 788 789 /** 790 * Read arguments, parse and compile an orchestra, read, process and 791 * load a score. 792 */ 793 PUBLIC int csoundCompileArgs(CSOUND *, int argc, const char **argv); 794 795 /** 796 * Prepares Csound for performance. Normally called after compiling 797 * a csd file or an orc file, in which case score preprocessing is 798 * performed and performance terminates when the score terminates. 799 * 800 * However, if called before compiling a csd file or an orc file, 801 * score preprocessing is not performed and "i" statements are dispatched 802 * as real-time events, the <CsOptions> tag is ignored, and performance 803 * continues indefinitely or until ended using the API. 804 */ 805 PUBLIC int csoundStart(CSOUND *csound); 806 807 /** 808 * Compiles Csound input files (such as an orchestra and score, or CSD) 809 * as directed by the supplied command-line arguments, 810 * but does not perform them. Returns a non-zero error code on failure. 811 * This function cannot be called during performance, and before a 812 * repeated call, csoundReset() needs to be called. 813 * In this (host-driven) mode, the sequence of calls should be as follows: 814 * /code 815 * csoundCompile(csound, argc, argv); 816 * while (!csoundPerformBuffer(csound)); 817 * csoundCleanup(csound); 818 * csoundReset(csound); 819 * /endcode 820 * Calls csoundStart() internally. 821 * Can only be called again after reset (see csoundReset()) 822 */ 823 PUBLIC int csoundCompile(CSOUND *, int argc, const char **argv); 824 825 /** 826 * Compiles a Csound input file (CSD, .csd file), but does not perform it. 827 * Returns a non-zero error code on failure. 828 * 829 * If csoundStart is called before csoundCompileCsd, the <CsOptions> 830 * element is ignored (but csoundSetOption can be called any number of 831 * times), the <CsScore> element is not pre-processed, but dispatched as 832 * real-time events; and performance continues indefinitely, or until 833 * ended by calling csoundStop or some other logic. In this "real-time" 834 * mode, the sequence of calls should be: 835 * 836 * \code 837 * 838 * csoundSetOption("-an_option"); 839 * csoundSetOption("-another_option"); 840 * csoundStart(csound); 841 * csoundCompileCsd(csound, csd_filename); 842 * while (1) { 843 * csoundPerformBuffer(csound); 844 * // Something to break out of the loop 845 * // when finished here... 846 * } 847 * csoundCleanup(csound); 848 * csoundReset(csound); 849 * 850 * \endcode 851 * 852 * NB: this function can be called repeatedly during performance to 853 * replace or add new instruments and events. 854 * 855 * But if csoundCompileCsd is called before csoundStart, the <CsOptions> 856 * element is used, the <CsScore> section is pre-processed and dispatched 857 * normally, and performance terminates when the score terminates, or 858 * csoundStop is called. In this "non-real-time" mode (which can still 859 * output real-time audio and handle real-time events), the sequence of 860 * calls should be: 861 * 862 * \code 863 * 864 * csoundCompileCsd(csound, csd_filename); 865 * csoundStart(csound); 866 * while (1) { 867 * int finished = csoundPerformBuffer(csound); 868 * if (finished) break; 869 * } 870 * csoundCleanup(csound); 871 * csoundReset(csound); 872 * 873 * \endcode 874 * 875 */ 876 PUBLIC int csoundCompileCsd(CSOUND *csound, const char *csd_filename); 877 878 /** 879 * Behaves the same way as csoundCompileCsd, except that the content 880 * of the CSD is read from the csd_text string rather than from a file. 881 * This is convenient when it is desirable to package the csd as part of 882 * an application or a multi-language piece. 883 */ 884 PUBLIC int csoundCompileCsdText(CSOUND *csound, const char *csd_text); 885 886 /** 887 * Senses input events and performs audio output until the end of score 888 * is reached (positive return value), an error occurs (negative return 889 * value), or performance is stopped by calling csoundStop() from another 890 * thread (zero return value). 891 * Note that csoundCompile() or csoundCompileOrc(), csoundReadScore(), 892 * csoundStart() must be called first. 893 * In the case of zero return value, csoundPerform() can be called again 894 * to continue the stopped performance. Otherwise, csoundReset() should be 895 * called to clean up after the finished or failed performance. 896 */ 897 PUBLIC int csoundPerform(CSOUND *); 898 899 /** 900 * Senses input events, and performs one control sample worth (ksmps) of 901 * audio output. 902 * Note that csoundCompile() or csoundCompileOrc(), csoundReadScore(), 903 * csoundStart() must be called first. 904 * Returns false during performance, and true when performance is finished. 905 * If called until it returns true, will perform an entire score. 906 * Enables external software to control the execution of Csound, 907 * and to synchronize performance with audio input and output. 908 */ 909 PUBLIC int csoundPerformKsmps(CSOUND *); 910 911 /** 912 * Performs Csound, sensing real-time and score events 913 * and processing one buffer's worth (-b frames) of interleaved audio. 914 * Note that csoundCompile must be called first, then call 915 * csoundGetOutputBuffer() and csoundGetInputBuffer() to get the pointer 916 * to csound's I/O buffers. 917 * Returns false during performance, and true when performance is finished. 918 */ 919 PUBLIC int csoundPerformBuffer(CSOUND *); 920 921 /** 922 * Stops a csoundPerform() running in another thread. Note that it is 923 * not guaranteed that csoundPerform() has already stopped when this 924 * function returns. 925 */ 926 PUBLIC void csoundStop(CSOUND *); 927 928 /** 929 * Prints information about the end of a performance, and closes audio 930 * and MIDI devices. 931 * Note: after calling csoundCleanup(), the operation of the perform 932 * functions is undefined. 933 */ 934 PUBLIC int csoundCleanup(CSOUND *); 935 936 /** 937 * Resets all internal memory and state in preparation for a new performance. 938 * Enables external software to run successive Csound performances 939 * without reloading Csound. Implies csoundCleanup(), unless already called. 940 */ 941 PUBLIC void csoundReset(CSOUND *); 942 943 /** @}*/ 944 /** @defgroup SERVER UDP server 945 * 946 * @{ */ 947 948 /** 949 * Starts the UDP server on a supplied port number 950 * returns CSOUND_SUCCESS if server has been started successfully, 951 * otherwise, CSOUND_ERROR. 952 */ 953 PUBLIC int csoundUDPServerStart(CSOUND *csound, unsigned int port); 954 955 /** returns the port number on which the server is running, or 956 * CSOUND_ERROR if the server is not running. 957 */ 958 PUBLIC int csoundUDPServerStatus(CSOUND *csound); 959 960 /** 961 * Closes the UDP server, returning CSOUND_SUCCESS if the 962 * running server was successfully closed, CSOUND_ERROR otherwise. 963 */ 964 PUBLIC int csoundUDPServerClose(CSOUND *csound); 965 966 /** 967 * Turns on the transmission of console messages to UDP on address addr 968 * port port. If mirror is one, the messages will continue to be 969 * sent to the usual destination (see csoundSetMessaggeCallback()) 970 * as well as to UDP. 971 * returns CSOUND_SUCCESS or CSOUND_ERROR if the UDP transmission 972 * could not be set up. 973 */ 974 PUBLIC int csoundUDPConsole(CSOUND *csound, const char *addr, 975 int port, int mirror); 976 977 /** 978 * Stop transmitting console messages via UDP 979 */ 980 PUBLIC void csoundStopUDPConsole(CSOUND *csound); 981 982 /** @}*/ 983 /** @defgroup ATTRIBUTES Attributes 984 * 985 * @{ */ 986 987 /** 988 * Returns the number of audio sample frames per second. 989 */ 990 PUBLIC MYFLT csoundGetSr(CSOUND *) ; 991 992 /** 993 * Returns the number of control samples per second. 994 */ 995 PUBLIC MYFLT csoundGetKr(CSOUND *); 996 997 /** 998 * Returns the number of audio sample frames per control sample. 999 */ 1000 PUBLIC uint32_t csoundGetKsmps(CSOUND *); 1001 1002 /** 1003 * Returns the number of audio output channels. Set through the nchnls 1004 * header variable in the csd file. 1005 */ 1006 PUBLIC uint32_t csoundGetNchnls(CSOUND *); 1007 1008 /** 1009 * Returns the number of audio input channels. Set through the 1010 * nchnls_i header variable in the csd file. If this variable is 1011 * not set, the value is taken from nchnls. 1012 */ 1013 PUBLIC uint32_t csoundGetNchnlsInput(CSOUND *csound); 1014 1015 /** 1016 * Returns the 0dBFS level of the spin/spout buffers. 1017 */ 1018 PUBLIC MYFLT csoundGet0dBFS(CSOUND *); 1019 1020 /** 1021 * Returns the A4 frequency reference 1022 */ 1023 PUBLIC MYFLT csoundGetA4(CSOUND *); 1024 1025 /** 1026 * Return the current performance time in samples 1027 */ 1028 PUBLIC int64_t csoundGetCurrentTimeSamples(CSOUND *csound); 1029 1030 /** 1031 * Return the size of MYFLT in bytes. 1032 */ 1033 PUBLIC int csoundGetSizeOfMYFLT(void); 1034 1035 /** 1036 * Returns host data. 1037 */ 1038 PUBLIC void *csoundGetHostData(CSOUND *); 1039 1040 /** 1041 * Sets host data. 1042 */ 1043 PUBLIC void csoundSetHostData(CSOUND *, void *hostData); 1044 1045 /** 1046 * Set a single csound option (flag). Returns CSOUND_SUCCESS on success. 1047 * NB: blank spaces are not allowed 1048 */ 1049 PUBLIC int csoundSetOption(CSOUND *csound, const char *option); 1050 1051 /** 1052 * Configure Csound with a given set of parameters defined in 1053 * the CSOUND_PARAMS structure. These parameters are the part of the 1054 * OPARMS struct that are configurable through command line flags. 1055 * The CSOUND_PARAMS structure can be obtained using csoundGetParams(). 1056 * These options should only be changed before performance has started. 1057 */ 1058 PUBLIC void csoundSetParams(CSOUND *csound, CSOUND_PARAMS *p); 1059 1060 /** 1061 * Get the current set of parameters from a CSOUND instance in 1062 * a CSOUND_PARAMS structure. See csoundSetParams(). 1063 */ 1064 PUBLIC void csoundGetParams(CSOUND *csound, CSOUND_PARAMS *p); 1065 1066 /** 1067 * Returns whether Csound is set to print debug messages sent through the 1068 * DebugMsg() internal API function. Anything different to 0 means true. 1069 */ 1070 PUBLIC int csoundGetDebug(CSOUND *); 1071 1072 /** 1073 * Sets whether Csound prints debug messages from the DebugMsg() internal 1074 * API function. Anything different to 0 means true. 1075 */ 1076 PUBLIC void csoundSetDebug(CSOUND *, int debug); 1077 1078 /** 1079 * If val > 0, sets the internal variable holding the system HW sr. 1080 * Returns the stored value containing the system HW sr. 1081 */ 1082 PUBLIC MYFLT csoundSystemSr(CSOUND *csound, MYFLT val); 1083 1084 1085 /** @}*/ 1086 /** @defgroup FILEIO General Input/Output 1087 * Setting the device or filename name for Csound input and output. These 1088 * functions are used to set the input and output command line flags that 1089 * apply to both input and output of audio and MIDI. See command line flags 1090 * -o, -i, -M and -Q in the Csound Reference Manual. 1091 * @{ */ 1092 1093 /** 1094 * Returns the audio output name (-o). 1095 */ 1096 PUBLIC const char *csoundGetOutputName(CSOUND *); 1097 1098 /** 1099 * Returns the audio input name (-i). 1100 */ 1101 PUBLIC const char *csoundGetInputName(CSOUND *); 1102 1103 /** 1104 * Set output destination, type and format 1105 * type can be one of "wav","aiff", "au","raw", "paf", "svx", "nist", "voc", 1106 * "ircam","w64","mat4", "mat5", "pvf","xi", "htk","sds","avr","wavex","sd2", 1107 * "flac", "caf","wve","ogg","mpc2k","rf64", or NULL (use default or 1108 * realtime IO). 1109 * format can be one of "alaw", "schar", "uchar", "float", "double", "long", 1110 * "short", "ulaw", "24bit", "vorbis", or NULL (use default or realtime IO). 1111 * For RT audio, use device_id from CS_AUDIODEVICE for a given audio device. 1112 * 1113 */ 1114 PUBLIC void csoundSetOutput(CSOUND *csound, const char *name, 1115 const char *type, const char *format); 1116 1117 /** 1118 * Get output type and format. 1119 * type should have space for at least 5 chars excluding termination, 1120 * and format should have space for at least 7 chars. 1121 * On return, these will hold the current values for 1122 * these parameters. 1123 */ 1124 PUBLIC void csoundGetOutputFormat(CSOUND *csound,char *type, 1125 char *format); 1126 1127 /** 1128 * Set input source 1129 */ 1130 PUBLIC void csoundSetInput(CSOUND *csound, const char *name); 1131 1132 /** 1133 * Set MIDI input device name/number 1134 */ 1135 PUBLIC void csoundSetMIDIInput(CSOUND *csound, const char *name); 1136 1137 /** 1138 * Set MIDI file input name 1139 */ 1140 PUBLIC void csoundSetMIDIFileInput(CSOUND *csound, const char *name); 1141 1142 /** 1143 * Set MIDI output device name/number 1144 */ 1145 PUBLIC void csoundSetMIDIOutput(CSOUND *csound, const char *name); 1146 1147 /** 1148 * Set MIDI file utput name 1149 */ 1150 PUBLIC void csoundSetMIDIFileOutput(CSOUND *csound, const char *name); 1151 1152 #if !defined(SWIG) 1153 /** 1154 * Sets an external callback for receiving notices whenever Csound opens 1155 * a file. The callback is made after the file is successfully opened. 1156 * The following information is passed to the callback: 1157 * char* pathname of the file; either full or relative to current dir 1158 * int a file type code from the enumeration CSOUND_FILETYPES 1159 * int 1 if Csound is writing the file, 0 if reading 1160 * int 1 if a temporary file that Csound will delete; 0 if not 1161 * 1162 * Pass NULL to disable the callback. 1163 * This callback is retained after a csoundReset() call. 1164 */ 1165 PUBLIC void csoundSetFileOpenCallback(CSOUND *p, 1166 void (*func)(CSOUND*, const char*, 1167 int, int, int)); 1168 #endif 1169 1170 /** @}*/ 1171 /** @defgroup RTAUDIOIO Realtime Audio I/O 1172 * 1173 * @{ */ 1174 1175 /** 1176 * Sets the current RT audio module 1177 */ 1178 PUBLIC void csoundSetRTAudioModule(CSOUND *csound, const char *module); 1179 1180 /** 1181 * retrieves a module name and type ("audio" or "midi") given a 1182 * number Modules are added to list as csound loads them returns 1183 * CSOUND_SUCCESS on success and CSOUND_ERROR if module number 1184 * was not found 1185 * 1186 * \code 1187 * char *name, *type; 1188 * int n = 0; 1189 * while(!csoundGetModule(csound, n++, &name, &type)) 1190 * printf("Module %d: %s (%s) \n", n, name, type); 1191 * \endcode 1192 */ 1193 PUBLIC int csoundGetModule(CSOUND *csound, int number, 1194 char **name, char **type); 1195 1196 /** 1197 * Returns the number of samples in Csound's input buffer. 1198 */ 1199 PUBLIC long csoundGetInputBufferSize(CSOUND *); 1200 1201 /** 1202 * Returns the number of samples in Csound's output buffer. 1203 */ 1204 PUBLIC long csoundGetOutputBufferSize(CSOUND *); 1205 1206 /** 1207 * Returns the address of the Csound audio input buffer. 1208 * Enables external software to write audio into Csound before calling 1209 * csoundPerformBuffer. 1210 */ 1211 PUBLIC MYFLT *csoundGetInputBuffer(CSOUND *); 1212 1213 /** 1214 * Returns the address of the Csound audio output buffer. 1215 * Enables external software to read audio from Csound after calling 1216 * csoundPerformBuffer. 1217 */ 1218 PUBLIC MYFLT *csoundGetOutputBuffer(CSOUND *); 1219 1220 /** 1221 * Returns the address of the Csound audio input working buffer (spin). 1222 * Enables external software to write audio into Csound before calling 1223 * csoundPerformKsmps. 1224 */ 1225 PUBLIC MYFLT *csoundGetSpin(CSOUND *); 1226 1227 /** 1228 * Clears the input buffer (spin). 1229 */ 1230 PUBLIC void csoundClearSpin(CSOUND *); 1231 1232 /** 1233 * Adds the indicated sample into the audio input working buffer (spin); 1234 * this only ever makes sense before calling csoundPerformKsmps(). 1235 * The frame and channel must be in bounds relative to ksmps and nchnls. 1236 * NB: the spin buffer needs to be cleared at every k-cycle by calling 1237 * csoundClearSpinBuffer(). 1238 */ 1239 PUBLIC void csoundAddSpinSample(CSOUND *csound, 1240 int frame, int channel, MYFLT sample); 1241 1242 /** 1243 * Sets the audio input working buffer (spin) to the indicated sample 1244 * this only ever makes sense before calling csoundPerformKsmps(). 1245 * The frame and channel must be in bounds relative to ksmps and nchnls. 1246 */ 1247 PUBLIC void csoundSetSpinSample(CSOUND *csound, 1248 int frame, int channel, MYFLT sample); 1249 1250 /** 1251 * Returns the address of the Csound audio output working buffer (spout). 1252 * Enables external software to read audio from Csound after calling 1253 * csoundPerformKsmps. 1254 */ 1255 PUBLIC MYFLT *csoundGetSpout(CSOUND *csound); 1256 1257 /** 1258 * Returns the indicated sample from the Csound audio output 1259 * working buffer (spout); only ever makes sense after calling 1260 * csoundPerformKsmps(). The frame and channel must be in bounds 1261 * relative to ksmps and nchnls. 1262 */ 1263 PUBLIC MYFLT csoundGetSpoutSample(CSOUND *csound, int frame, int channel); 1264 1265 /** 1266 * Return pointer to user data pointer for real time audio input. 1267 */ 1268 PUBLIC void **csoundGetRtRecordUserData(CSOUND *); 1269 1270 /** 1271 * Return pointer to user data pointer for real time audio output. 1272 */ 1273 PUBLIC void **csoundGetRtPlayUserData(CSOUND *); 1274 1275 /** 1276 * Calling this function with a non-zero 'state' value between 1277 * csoundCreate() and the start of performance will disable all default 1278 * handling of sound I/O by the Csound library, allowing the host 1279 * application to use the spin/spout/input/output buffers directly. 1280 * For applications using spin/spout, bufSize should be set to 0. 1281 * If 'bufSize' is greater than zero, the buffer size (-b) in frames will be 1282 * set to the integer multiple of ksmps that is nearest to the value 1283 * specified. 1284 */ 1285 PUBLIC void csoundSetHostImplementedAudioIO(CSOUND *, 1286 int state, int bufSize); 1287 1288 1289 /** 1290 * This function can be called to obtain a list of available 1291 * input or output audio devices. If list is NULL, the function 1292 * will only return the number of devices (isOutput=1 for out 1293 * devices, 0 for in devices). 1294 * If list is non-NULL, then it should contain enough memory for 1295 * one CS_AUDIODEVICE structure per device. 1296 * Hosts will typically call this function twice: first to obtain 1297 * a number of devices, then, after allocating space for each 1298 * device information structure, pass an array of CS_AUDIODEVICE 1299 * structs to be filled: 1300 * 1301 * \code 1302 * int i,n = csoundGetAudioDevList(csound,NULL,1); 1303 * CS_AUDIODEVICE *devs = (CS_AUDIODEVICE *) 1304 * malloc(n*sizeof(CS_AUDIODEVICE)); 1305 * csoundGetAudioDevList(csound,devs,1); 1306 * for(i=0; i < n; i++) 1307 * csound->Message(csound, " %d: %s (%s)\n", 1308 * i, devs[i].device_id, devs[i].device_name); 1309 * free(devs); 1310 * \endcode 1311 */ 1312 PUBLIC int csoundGetAudioDevList(CSOUND *csound, 1313 CS_AUDIODEVICE *list, int isOutput); 1314 1315 /** 1316 * Sets a function to be called by Csound for opening real-time 1317 * audio playback. 1318 */ 1319 PUBLIC void 1320 csoundSetPlayopenCallback(CSOUND *, 1321 int (*playopen__)(CSOUND *, 1322 const csRtAudioParams *parm)); 1323 1324 /** 1325 * Sets a function to be called by Csound for performing real-time 1326 * audio playback. 1327 */ 1328 PUBLIC void csoundSetRtplayCallback(CSOUND *, 1329 void (*rtplay__)(CSOUND *, 1330 const MYFLT *outBuf, 1331 int nbytes)); 1332 1333 /** 1334 * Sets a function to be called by Csound for opening real-time 1335 * audio recording. 1336 */ 1337 PUBLIC void csoundSetRecopenCallback(CSOUND *, 1338 int (*recopen_)(CSOUND *, 1339 const csRtAudioParams *parm)); 1340 1341 /** 1342 * Sets a function to be called by Csound for performing real-time 1343 * audio recording. 1344 */ 1345 PUBLIC void csoundSetRtrecordCallback(CSOUND *, 1346 int (*rtrecord__)(CSOUND *, 1347 MYFLT *inBuf, 1348 int nbytes)); 1349 1350 /** 1351 * Sets a function to be called by Csound for closing real-time 1352 * audio playback and recording. 1353 */ 1354 PUBLIC void csoundSetRtcloseCallback(CSOUND *, void (*rtclose__)(CSOUND *)); 1355 1356 /** 1357 * Sets a function that is called to obtain a list of audio devices. 1358 * This should be set by rtaudio modules and should not be set by hosts. 1359 * (See csoundGetAudioDevList()) 1360 */ 1361 PUBLIC void csoundSetAudioDeviceListCallback(CSOUND *csound, 1362 int (*audiodevlist__)(CSOUND *, 1363 CS_AUDIODEVICE *list, 1364 int isOutput)); 1365 1366 /** @}*/ 1367 /** @defgroup RTMIDI Realtime Midi I/O 1368 * 1369 * @{ */ 1370 1371 /** 1372 * Sets the current MIDI IO module 1373 */ 1374 PUBLIC void csoundSetMIDIModule(CSOUND *csound, const char *module); 1375 1376 /** 1377 * call this function with state 1 if the host is implementing 1378 * MIDI via the callbacks below. 1379 */ 1380 PUBLIC void csoundSetHostImplementedMIDIIO(CSOUND *csound, 1381 int state); 1382 1383 /** 1384 * This function can be called to obtain a list of available 1385 * input or output midi devices. If list is NULL, the function 1386 * will only return the number of devices (isOutput=1 for out 1387 * devices, 0 for in devices). 1388 * If list is non-NULL, then it should contain enough memory for 1389 * one CS_MIDIDEVICE structure per device. 1390 * Hosts will typically call this function twice: first to obtain 1391 * a number of devices, then, after allocating space for each 1392 * device information structure, pass an array of CS_MIDIDEVICE 1393 * structs to be filled. (see also csoundGetAudioDevList()) 1394 */ 1395 PUBLIC int csoundGetMIDIDevList(CSOUND *csound, 1396 CS_MIDIDEVICE *list, int isOutput); 1397 1398 /** 1399 * Sets callback for opening real time MIDI input. 1400 */ 1401 PUBLIC void csoundSetExternalMidiInOpenCallback(CSOUND *, 1402 int (*func)(CSOUND *, 1403 void **userData, 1404 const char *devName)); 1405 1406 /** 1407 * Sets callback for reading from real time MIDI input. 1408 */ 1409 PUBLIC void csoundSetExternalMidiReadCallback(CSOUND *, 1410 int (*func)(CSOUND *, 1411 void *userData, 1412 unsigned char *buf, 1413 int nBytes)); 1414 1415 /** 1416 * Sets callback for closing real time MIDI input. 1417 */ 1418 PUBLIC void csoundSetExternalMidiInCloseCallback(CSOUND *, 1419 int (*func)(CSOUND *, 1420 void *userData)); 1421 1422 /** 1423 * Sets callback for opening real time MIDI output. 1424 */ 1425 PUBLIC void csoundSetExternalMidiOutOpenCallback(CSOUND *, 1426 int (*func)(CSOUND *, 1427 void **userData, 1428 const char *devName)); 1429 1430 /** 1431 * Sets callback for writing to real time MIDI output. 1432 */ 1433 PUBLIC void csoundSetExternalMidiWriteCallback(CSOUND *, 1434 int (*func)(CSOUND *, 1435 void *userData, 1436 const unsigned char *buf, 1437 int nBytes)); 1438 1439 /** 1440 * Sets callback for closing real time MIDI output. 1441 */ 1442 PUBLIC void csoundSetExternalMidiOutCloseCallback(CSOUND *, 1443 int (*func)(CSOUND *, 1444 void *userData)); 1445 1446 /** 1447 * Sets callback for converting MIDI error codes to strings. 1448 */ 1449 PUBLIC void csoundSetExternalMidiErrorStringCallback(CSOUND *, 1450 const char *(*func)(int)); 1451 1452 1453 /** 1454 * Sets a function that is called to obtain a list of MIDI devices. 1455 * This should be set by IO plugins, and should not be used by hosts. 1456 * (See csoundGetMIDIDevList()) 1457 */ 1458 PUBLIC void csoundSetMIDIDeviceListCallback(CSOUND *csound, 1459 int (*mididevlist__)(CSOUND *, 1460 CS_MIDIDEVICE *list, 1461 int isOutput)); 1462 1463 /** @}*/ 1464 /** @defgroup SCOREHANDLING Score Handling 1465 * 1466 * @{ */ 1467 1468 /** 1469 * Read, preprocess, and load a score from an ASCII string 1470 * It can be called repeatedly, with the new score events 1471 * being added to the currently scheduled ones. 1472 */ 1473 PUBLIC int csoundReadScore(CSOUND *csound, const char *str); 1474 1475 /** 1476 * Asynchronous version of csoundReadScore(). 1477 */ 1478 PUBLIC void csoundReadScoreAsync(CSOUND *csound, const char *str); 1479 1480 /** 1481 * Returns the current score time in seconds 1482 * since the beginning of performance. 1483 */ 1484 PUBLIC double csoundGetScoreTime(CSOUND *); 1485 1486 /** 1487 * Sets whether Csound score events are performed or not, independently 1488 * of real-time MIDI events (see csoundSetScorePending()). 1489 */ 1490 PUBLIC int csoundIsScorePending(CSOUND *); 1491 1492 /** 1493 * Sets whether Csound score events are performed or not (real-time 1494 * events will continue to be performed). Can be used by external software, 1495 * such as a VST host, to turn off performance of score events (while 1496 * continuing to perform real-time events), for example to 1497 * mute a Csound score while working on other tracks of a piece, or 1498 * to play the Csound instruments live. 1499 */ 1500 PUBLIC void csoundSetScorePending(CSOUND *, int pending); 1501 1502 /** 1503 * Returns the score time beginning at which score events will 1504 * actually immediately be performed (see csoundSetScoreOffsetSeconds()). 1505 */ 1506 PUBLIC MYFLT csoundGetScoreOffsetSeconds(CSOUND *); 1507 1508 /** 1509 * Csound score events prior to the specified time are not performed, and 1510 * performance begins immediately at the specified time (real-time events 1511 * will continue to be performed as they are received). 1512 * Can be used by external software, such as a VST host, 1513 * to begin score performance midway through a Csound score, 1514 * for example to repeat a loop in a sequencer, or to synchronize 1515 * other events with the Csound score. 1516 */ 1517 PUBLIC void csoundSetScoreOffsetSeconds(CSOUND *, MYFLT time); 1518 1519 /** 1520 * Rewinds a compiled Csound score to the time specified with 1521 * csoundSetScoreOffsetSeconds(). 1522 */ 1523 PUBLIC void csoundRewindScore(CSOUND *); 1524 1525 /** 1526 * Sets an external callback for Cscore processing. 1527 * Pass NULL to reset to the internal cscore() function 1528 * (which does nothing). 1529 * This callback is retained after a csoundReset() call. 1530 */ 1531 PUBLIC void csoundSetCscoreCallback(CSOUND *, 1532 void (*cscoreCallback_)(CSOUND *)); 1533 1534 /** 1535 * Sorts score file 'inFile' and writes the result to 'outFile'. 1536 * The Csound instance should be initialised 1537 * before calling this function, and csoundReset() should be called 1538 * after sorting the score to clean up. On success, zero is returned. 1539 */ 1540 PUBLIC int csoundScoreSort(CSOUND *, FILE *inFile, FILE *outFile); 1541 1542 /** 1543 * Extracts from 'inFile', controlled by 'extractFile', and writes 1544 * the result to 'outFile'. The Csound instance should be initialised 1545 * before calling this function, and csoundReset() 1546 * should be called after score extraction to clean up. 1547 * The return value is zero on success. 1548 */ 1549 PUBLIC int csoundScoreExtract(CSOUND *, 1550 FILE *inFile, FILE *outFile, FILE *extractFile); 1551 1552 /** @}*/ 1553 /** @defgroup MESSAGES Messages and Text 1554 * 1555 * @{ */ 1556 1557 /** 1558 * Displays an informational message. 1559 */ 1560 PUBLIC CS_PRINTF2 void csoundMessage(CSOUND *, const char *format, ...); 1561 1562 /** 1563 * Print message with special attributes (see msg_attr.h for the list of 1564 * available attributes). With attr=0, csoundMessageS() is identical to 1565 * csoundMessage(). 1566 */ 1567 PUBLIC CS_PRINTF3 void csoundMessageS(CSOUND *, 1568 int attr, const char *format, ...); 1569 1570 PUBLIC void csoundMessageV(CSOUND *, 1571 int attr, const char *format, va_list args); 1572 1573 PUBLIC void csoundSetDefaultMessageCallback(void (*csoundMessageCallback_)( 1574 CSOUND *, 1575 int attr, 1576 const char *format, 1577 va_list valist)); 1578 1579 /** 1580 * Sets a function to be called by Csound to print an informational message. 1581 * This callback is never called on --realtime mode 1582 */ 1583 PUBLIC void csoundSetMessageCallback(CSOUND *, 1584 void (*csoundMessageCallback_)(CSOUND *, 1585 int attr, 1586 const char *format, 1587 va_list valist)); 1588 1589 /** 1590 * Sets an alternative function to be called by Csound to print an 1591 * informational message, using a less granular signature. 1592 * This callback can be set for --realtime mode. 1593 * This callback is cleared after csoundReset 1594 */ 1595 PUBLIC void csoundSetMessageStringCallback(CSOUND *csound, 1596 void (*csoundMessageStrCallback)(CSOUND *csound, 1597 int attr, 1598 const char *str)); 1599 1600 /** 1601 * Returns the Csound message level (from 0 to 231). 1602 */ 1603 PUBLIC int csoundGetMessageLevel(CSOUND *); 1604 1605 /** 1606 * Sets the Csound message level (from 0 to 231). 1607 */ 1608 PUBLIC void csoundSetMessageLevel(CSOUND *, int messageLevel); 1609 1610 /** 1611 * Creates a buffer for storing messages printed by Csound. 1612 * Should be called after creating a Csound instance andthe buffer 1613 * can be freed by calling csoundDestroyMessageBuffer() before 1614 * deleting the Csound instance. You will generally want to call 1615 * csoundCleanup() to make sure the last messages are flushed to 1616 * the message buffer before destroying Csound. 1617 * If 'toStdOut' is non-zero, the messages are also printed to 1618 * stdout and stderr (depending on the type of the message), 1619 * in addition to being stored in the buffer. 1620 * Using the message buffer ties up the internal message callback, so 1621 * csoundSetMessageCallback should not be called after creating the 1622 * message buffer. 1623 */ 1624 PUBLIC void csoundCreateMessageBuffer(CSOUND *csound, int toStdOut); 1625 1626 /** 1627 * Returns the first message from the buffer. 1628 */ 1629 PUBLIC const char* csoundGetFirstMessage(CSOUND *csound); 1630 1631 /** 1632 * Returns the attribute parameter (see msg_attr.h) of the first message 1633 * in the buffer. 1634 */ 1635 PUBLIC int csoundGetFirstMessageAttr(CSOUND *csound); 1636 1637 /** 1638 * Removes the first message from the buffer. 1639 */ 1640 PUBLIC void csoundPopFirstMessage(CSOUND *csound); 1641 1642 /** 1643 * Returns the number of pending messages in the buffer. 1644 */ 1645 PUBLIC int csoundGetMessageCnt(CSOUND *csound); 1646 1647 /** 1648 * Releases all memory used by the message buffer. 1649 */ 1650 void PUBLIC csoundDestroyMessageBuffer(CSOUND *csound); 1651 1652 /** @}*/ 1653 /** @defgroup CONTROLEVENTS Channels, Control and Events 1654 * 1655 * @{ */ 1656 1657 /** 1658 * Stores a pointer to the specified channel of the bus in *p, 1659 * creating the channel first if it does not exist yet. 1660 * 'type' must be the bitwise OR of exactly one of the following values, 1661 * CSOUND_CONTROL_CHANNEL 1662 * control data (one MYFLT value) 1663 * CSOUND_AUDIO_CHANNEL 1664 * audio data (csoundGetKsmps(csound) MYFLT values) 1665 * CSOUND_STRING_CHANNEL 1666 * string data (MYFLT values with enough space to store 1667 * csoundGetChannelDatasize() characters, including the 1668 * NULL character at the end of the string) 1669 * and at least one of these: 1670 * CSOUND_INPUT_CHANNEL 1671 * CSOUND_OUTPUT_CHANNEL 1672 * If the channel already exists, it must match the data type 1673 * (control, audio, or string), however, the input/output bits are 1674 * OR'd with the new value. Note that audio and string channels 1675 * can only be created after calling csoundCompile(), because the 1676 * storage size is not known until then. 1677 1678 * Return value is zero on success, or a negative error code, 1679 * CSOUND_MEMORY there is not enough memory for allocating the channel 1680 * CSOUND_ERROR the specified name or type is invalid 1681 * or, if a channel with the same name but incompatible type 1682 * already exists, the type of the existing channel. In the case 1683 * of any non-zero return value, *p is set to NULL. 1684 * Note: to find out the type of a channel without actually 1685 * creating or changing it, set 'type' to zero, so that the return 1686 * value will be either the type of the channel, or CSOUND_ERROR 1687 * if it does not exist. 1688 * 1689 * Operations on **p are not thread-safe by default. The host is required 1690 * to take care of threadsafety by 1691 * 1) with control channels use __atomic_load() or 1692 * __atomic_store() gcc atomic builtins to get or set a channel, 1693 * if available. 1694 * 2) For string and audio channels (and controls if option 1 is not 1695 * available), retrieve the channel lock with csoundGetChannelLock() 1696 * and use csoundSpinLock() and csoundSpinUnLock() to protect access 1697 * to **p. 1698 * See Top/threadsafe.c in the Csound library sources for 1699 * examples. Optionally, use the channel get/set functions 1700 * provided below, which are threadsafe by default. 1701 */ 1702 PUBLIC int csoundGetChannelPtr(CSOUND *, 1703 MYFLT **p, const char *name, int type); 1704 1705 /** 1706 * Returns a list of allocated channels in *lst. A controlChannelInfo_t 1707 * structure contains the channel characteristics. 1708 * The return value is the number of channels, which may be zero if there 1709 * are none, or CSOUND_MEMORY if there is not enough memory for allocating 1710 * the list. In the case of no channels or an error, *lst is set to NULL. 1711 * Notes: the caller is responsible for freeing the list returned in *lst 1712 * with csoundDeleteChannelList(). The name pointers may become invalid 1713 * after calling csoundReset(). 1714 */ 1715 PUBLIC int csoundListChannels(CSOUND *, controlChannelInfo_t **lst); 1716 1717 /** 1718 * Releases a channel list previously returned by csoundListChannels(). 1719 */ 1720 PUBLIC void csoundDeleteChannelList(CSOUND *, controlChannelInfo_t *lst); 1721 1722 /** 1723 * Set parameters hints for a control channel. These hints have no internal 1724 * function but can be used by front ends to construct GUIs or to constrain 1725 * values. See the controlChannelHints_t structure for details. 1726 * Returns zero on success, or a non-zero error code on failure: 1727 * CSOUND_ERROR: the channel does not exist, is not a control channel, 1728 * or the specified parameters are invalid 1729 * CSOUND_MEMORY: could not allocate memory 1730 */ 1731 PUBLIC int csoundSetControlChannelHints(CSOUND *, const char *name, 1732 controlChannelHints_t hints); 1733 1734 /** 1735 * Returns special parameters (assuming there are any) of a control channel, 1736 * previously set with csoundSetControlChannelHints() or the chnparams 1737 * opcode. 1738 * If the channel exists, is a control channel, the channel hints 1739 * are stored in the preallocated controlChannelHints_t structure. The 1740 * attributes member of the structure will be allocated inside this function 1741 * so it is necessary to free it explicitly in the host. 1742 * 1743 * The return value is zero if the channel exists and is a control 1744 * channel, otherwise, an error code is returned. 1745 */ 1746 PUBLIC int csoundGetControlChannelHints(CSOUND *, const char *name, 1747 controlChannelHints_t *hints); 1748 1749 /** 1750 * Recovers a pointer to a lock for the specified channel called 'name'. 1751 * The returned lock can be locked/unlocked with the csoundSpinLock() 1752 * and csoundSpinUnLock() functions. 1753 * @returns the address of the lock or NULL if the channel does not exist 1754 */ 1755 PUBLIC int *csoundGetChannelLock(CSOUND *, const char *name); 1756 1757 /** 1758 * retrieves the value of control channel identified by *name. 1759 * If the err argument is not NULL, the error (or success) code 1760 * finding or accessing the channel is stored in it. 1761 */ 1762 PUBLIC MYFLT csoundGetControlChannel(CSOUND *csound, const char *name, 1763 int *err); 1764 1765 /** 1766 * sets the value of control channel identified by *name 1767 */ 1768 PUBLIC void csoundSetControlChannel(CSOUND *csound, 1769 const char *name, MYFLT val); 1770 1771 /** 1772 * copies the audio channel identified by *name into array 1773 * *samples which should contain enough memory for ksmps MYFLTs 1774 */ 1775 PUBLIC void csoundGetAudioChannel(CSOUND *csound, 1776 const char *name, MYFLT *samples); 1777 1778 /** 1779 * sets the audio channel identified by *name with data from array 1780 * *samples which should contain at least ksmps MYFLTs 1781 */ 1782 PUBLIC void csoundSetAudioChannel(CSOUND *csound, 1783 const char *name, MYFLT *samples); 1784 1785 /** 1786 * copies the string channel identified by *name into *string 1787 * which should contain enough memory for the string 1788 * (see csoundGetChannelDatasize() below) 1789 */ 1790 PUBLIC void csoundGetStringChannel(CSOUND *csound, 1791 const char *name, char *string); 1792 1793 /** 1794 * sets the string channel identified by *name with *string 1795 */ 1796 PUBLIC void csoundSetStringChannel(CSOUND *csound, 1797 const char *name, char *string); 1798 1799 /** 1800 * returns the size of data stored in a channel; for string channels 1801 * this might change if the channel space gets reallocated 1802 * Since string variables use dynamic memory allocation in Csound6, 1803 * this function can be called to get the space required for 1804 * csoundGetStringChannel() 1805 */ 1806 PUBLIC int csoundGetChannelDatasize(CSOUND *csound, const char *name); 1807 1808 /** Sets the function which will be called whenever the invalue opcode 1809 * is used. */ 1810 PUBLIC void 1811 csoundSetInputChannelCallback(CSOUND *csound, 1812 channelCallback_t inputChannelCalback); 1813 1814 /** Sets the function which will be called whenever the outvalue opcode 1815 * is used. */ 1816 PUBLIC void 1817 csoundSetOutputChannelCallback(CSOUND *csound, 1818 channelCallback_t outputChannelCalback); 1819 1820 /** 1821 * Sends a PVSDATEX fin to the pvsin opcode (f-rate) for channel 'name'. 1822 * Returns zero on success, CSOUND_ERROR if the index is invalid or 1823 * fsig framesizes are incompatible. 1824 * CSOUND_MEMORY if there is not enough memory to extend the bus. 1825 */ 1826 PUBLIC int csoundSetPvsChannel(CSOUND *, const PVSDATEXT *fin, 1827 const char *name); 1828 1829 /** 1830 * Receives a PVSDAT fout from the pvsout opcode (f-rate) at channel 'name' 1831 * Returns zero on success, CSOUND_ERROR if the index is invalid or 1832 * if fsig framesizes are incompatible. 1833 * CSOUND_MEMORY if there is not enough memory to extend the bus 1834 */ 1835 PUBLIC int csoundGetPvsChannel(CSOUND *csound, PVSDATEXT *fout, 1836 const char *name); 1837 1838 /** 1839 * Send a new score event. 'type' is the score event type ('a', 'i', 'q', 1840 * 'f', or 'e'). 1841 * 'numFields' is the size of the pFields array. 'pFields' is an array of 1842 * floats with all the pfields for this event, starting with the p1 value 1843 * specified in pFields[0]. 1844 */ 1845 PUBLIC int csoundScoreEvent(CSOUND *, 1846 char type, const MYFLT *pFields, long numFields); 1847 1848 /** 1849 * Asynchronous version of csoundScoreEvent(). 1850 */ 1851 PUBLIC void csoundScoreEventAsync(CSOUND *, 1852 char type, const MYFLT *pFields, long numFields); 1853 1854 /** 1855 * Like csoundScoreEvent(), this function inserts a score event, but 1856 * at absolute time with respect to the start of performance, or from an 1857 * offset set with time_ofs 1858 */ 1859 PUBLIC int csoundScoreEventAbsolute(CSOUND *, 1860 char type, const MYFLT *pfields, long numFields, double time_ofs); 1861 1862 /** 1863 * Asynchronous version of csoundScoreEventAbsolute(). 1864 */ 1865 PUBLIC void csoundScoreEventAbsoluteAsync(CSOUND *, 1866 char type, const MYFLT *pfields, long numFields, double time_ofs); 1867 /** 1868 * Input a NULL-terminated string (as if from a console), 1869 * used for line events. 1870 */ 1871 PUBLIC void csoundInputMessage(CSOUND *, const char *message); 1872 1873 /** 1874 * Asynchronous version of csoundInputMessage(). 1875 */ 1876 PUBLIC void csoundInputMessageAsync(CSOUND *, const char *message); 1877 1878 /** 1879 * Kills off one or more running instances of an instrument identified 1880 * by instr (number) or instrName (name). If instrName is NULL, the 1881 * instrument number is used. 1882 * Mode is a sum of the following values: 1883 * 0,1,2: kill all instances (1), oldest only (1), or newest (2) 1884 * 4: only turnoff notes with exactly matching (fractional) instr number 1885 * 8: only turnoff notes with indefinite duration (p3 < 0 or MIDI) 1886 * allow_release, if non-zero, the killed instances are allowed to release. 1887 */ 1888 PUBLIC int csoundKillInstance(CSOUND *csound, MYFLT instr, 1889 char *instrName, int mode, int allow_release); 1890 1891 1892 /** 1893 * Register a function to be called once in every control period 1894 * by sensevents(). Any number of functions may be registered, 1895 * and will be called in the order of registration. 1896 * The callback function takes two arguments: the Csound instance 1897 * pointer, and the userData pointer as passed to this function. 1898 * This facility can be used to ensure a function is called synchronously 1899 * before every csound control buffer processing. It is important 1900 * to make sure no blocking operations are performed in the callback. 1901 * The callbacks are cleared on csoundCleanup(). 1902 * Returns zero on success. 1903 */ 1904 PUBLIC int csoundRegisterSenseEventCallback(CSOUND *, 1905 void (*func)(CSOUND *, void *), 1906 void *userData); 1907 1908 /** 1909 * Set the ASCII code of the most recent key pressed. 1910 * This value is used by the 'sensekey' opcode if a callback 1911 * for returning keyboard events is not set (see 1912 * csoundRegisterKeyboardCallback()). 1913 */ 1914 PUBLIC void csoundKeyPress(CSOUND *, char c); 1915 1916 /** 1917 * Registers general purpose callback functions that will be called to query 1918 * keyboard events. These callbacks are called on every control period by 1919 * the sensekey opcode. 1920 * The callback is preserved on csoundReset(), and multiple 1921 * callbacks may be set and will be called in reverse order of 1922 * registration. If the same function is set again, it is only moved 1923 * in the list of callbacks so that it will be called first, and the 1924 * user data and type mask parameters are updated. 'typeMask' can be the 1925 * bitwise OR of callback types for which the function should be called, 1926 * or zero for all types. 1927 * Returns zero on success, CSOUND_ERROR if the specified function 1928 * pointer or type mask is invalid, and CSOUND_MEMORY if there is not 1929 * enough memory. 1930 * 1931 * The callback function takes the following arguments: 1932 * void *userData 1933 * the "user data" pointer, as specified when setting the callback 1934 * void *p 1935 * data pointer, depending on the callback type 1936 * unsigned int type 1937 * callback type, can be one of the following (more may be added in 1938 * future versions of Csound): 1939 * CSOUND_CALLBACK_KBD_EVENT 1940 * CSOUND_CALLBACK_KBD_TEXT 1941 * called by the sensekey opcode to fetch key codes. The data 1942 * pointer is a pointer to a single value of type 'int', for 1943 * returning the key code, which can be in the range 1 to 65535, 1944 * or 0 if there is no keyboard event. 1945 * For CSOUND_CALLBACK_KBD_EVENT, both key press and release 1946 * events should be returned (with 65536 (0x10000) added to the 1947 * key code in the latter case) as unshifted ASCII codes. 1948 * CSOUND_CALLBACK_KBD_TEXT expects key press events only as the 1949 * actual text that is typed. 1950 * The return value should be zero on success, negative on error, and 1951 * positive if the callback was ignored (for example because the type is 1952 * not known). 1953 */ 1954 PUBLIC int csoundRegisterKeyboardCallback(CSOUND *, 1955 int (*func)(void *userData, void *p, 1956 unsigned int type), 1957 void *userData, unsigned int type); 1958 1959 /** 1960 * Removes a callback previously set with csoundRegisterKeyboardCallback(). 1961 */ 1962 PUBLIC void csoundRemoveKeyboardCallback(CSOUND *csound, 1963 int (*func)(void *, void *, unsigned int)); 1964 1965 /** @}*/ 1966 /** @defgroup TABLE Tables 1967 * 1968 * @{ */ 1969 /** 1970 * Returns the length of a function table (not including the guard point), 1971 * or -1 if the table does not exist. 1972 */ 1973 PUBLIC int csoundTableLength(CSOUND *, int table); 1974 1975 /** 1976 * Returns the value of a slot in a function table. 1977 * The table number and index are assumed to be valid. 1978 */ 1979 PUBLIC MYFLT csoundTableGet(CSOUND *, int table, int index); 1980 1981 /** 1982 * Sets the value of a slot in a function table. 1983 * The table number and index are assumed to be valid. 1984 */ 1985 PUBLIC void csoundTableSet(CSOUND *, int table, int index, MYFLT value); 1986 1987 1988 /** 1989 * Copy the contents of a function table into a supplied array *dest 1990 * The table number is assumed to be valid, and the destination needs to 1991 * have sufficient space to receive all the function table contents. 1992 */ 1993 PUBLIC void csoundTableCopyOut(CSOUND *csound, int table, MYFLT *dest); 1994 1995 /** 1996 * Asynchronous version of csoundTableCopyOut() 1997 */ 1998 PUBLIC void csoundTableCopyOutAsync(CSOUND *csound, int table, MYFLT *dest); 1999 /** 2000 * Copy the contents of an array *src into a given function table 2001 * The table number is assumed to be valid, and the table needs to 2002 * have sufficient space to receive all the array contents. 2003 */ 2004 PUBLIC void csoundTableCopyIn(CSOUND *csound, int table, MYFLT *src); 2005 2006 /** 2007 * Asynchronous version of csoundTableCopyIn() 2008 */ 2009 PUBLIC void csoundTableCopyInAsync(CSOUND *csound, int table, MYFLT *src); 2010 2011 /** 2012 * Stores pointer to function table 'tableNum' in *tablePtr, 2013 * and returns the table length (not including the guard point). 2014 * If the table does not exist, *tablePtr is set to NULL and 2015 * -1 is returned. 2016 */ 2017 PUBLIC int csoundGetTable(CSOUND *, MYFLT **tablePtr, int tableNum); 2018 2019 /** 2020 * Stores pointer to the arguments used to generate 2021 * function table 'tableNum' in *argsPtr, 2022 * and returns the number of arguments used. 2023 * If the table does not exist, *argsPtr is set to NULL and 2024 * -1 is returned. 2025 * NB: the argument list starts with the GEN number and is followed by 2026 * its parameters. eg. f 1 0 1024 10 1 0.5 yields the list {10.0,1.0,0.5} 2027 */ 2028 PUBLIC int csoundGetTableArgs(CSOUND *csound, MYFLT **argsPtr, int tableNum); 2029 2030 /** 2031 * Checks if a given GEN number num is a named GEN 2032 * if so, it returns the string length (excluding terminating NULL char) 2033 * Otherwise it returns 0. 2034 */ 2035 PUBLIC int csoundIsNamedGEN(CSOUND *csound, int num); 2036 2037 /** 2038 * Gets the GEN name from a number num, if this is a named GEN 2039 * The final parameter is the max len of the string (excluding termination) 2040 */ 2041 PUBLIC void csoundGetNamedGEN(CSOUND *csound, int num, char *name, int len); 2042 2043 /** @}*/ 2044 /** @defgroup TABLEDISPLAY Function table display 2045 * 2046 * @{ */ 2047 /** 2048 * Tells Csound whether external graphic table display is supported. 2049 * Returns the previously set value (initially zero). 2050 */ 2051 PUBLIC int csoundSetIsGraphable(CSOUND *, int isGraphable); 2052 2053 /** 2054 * Called by external software to set Csound's MakeGraph function. 2055 */ 2056 PUBLIC void csoundSetMakeGraphCallback(CSOUND *, 2057 void (*makeGraphCallback_)(CSOUND *, 2058 WINDAT *windat, 2059 const char *name)); 2060 2061 /** 2062 * Called by external software to set Csound's DrawGraph function. 2063 */ 2064 PUBLIC void csoundSetDrawGraphCallback(CSOUND *, 2065 void (*drawGraphCallback_)(CSOUND *, 2066 WINDAT *windat)); 2067 2068 /** 2069 * Called by external software to set Csound's KillGraph function. 2070 */ 2071 PUBLIC void csoundSetKillGraphCallback(CSOUND *, 2072 void (*killGraphCallback_)(CSOUND *, 2073 WINDAT *windat)); 2074 2075 /** 2076 * Called by external software to set Csound's ExitGraph function. 2077 */ 2078 PUBLIC void csoundSetExitGraphCallback(CSOUND *, 2079 int (*exitGraphCallback_)(CSOUND *)); 2080 2081 /** @}*/ 2082 /** @defgroup OPCODES Opcodes 2083 * 2084 * @{ */ 2085 2086 /** 2087 * Finds the list of named gens 2088 */ 2089 PUBLIC void *csoundGetNamedGens(CSOUND *); 2090 2091 /** 2092 * Gets an alphabetically sorted list of all opcodes. 2093 * Should be called after externals are loaded by csoundCompile(). 2094 * Returns the number of opcodes, or a negative error code on failure. 2095 * Make sure to call csoundDisposeOpcodeList() when done with the list. 2096 */ 2097 PUBLIC int csoundNewOpcodeList(CSOUND *, opcodeListEntry **opcodelist); 2098 2099 /** 2100 * Releases an opcode list. 2101 */ 2102 PUBLIC void csoundDisposeOpcodeList(CSOUND *, opcodeListEntry *opcodelist); 2103 2104 /** 2105 * Appends an opcode implemented by external software 2106 * to Csound's internal opcode list. 2107 * The opcode list is extended by one slot, 2108 * and the parameters are copied into the new slot. 2109 * Returns zero on success. 2110 */ 2111 PUBLIC int csoundAppendOpcode(CSOUND *, const char *opname, 2112 int dsblksiz, int flags, int thread, 2113 const char *outypes, const char *intypes, 2114 int (*iopadr)(CSOUND *, void *), 2115 int (*kopadr)(CSOUND *, void *), 2116 int (*aopadr)(CSOUND *, void *)); 2117 2118 /** @}*/ 2119 /** @defgroup THREADING Threading and concurrency 2120 * 2121 * @{ */ 2122 2123 /** 2124 * Called by external software to set a function for checking system 2125 * events, yielding cpu time for coopertative multitasking, etc. 2126 * This function is optional. It is often used as a way to 'turn off' 2127 * Csound, allowing it to exit gracefully. In addition, some operations 2128 * like utility analysis routines are not reentrant and you should use 2129 * this function to do any kind of updating during the operation. 2130 * Returns an 'OK to continue' boolean. 2131 */ 2132 PUBLIC void csoundSetYieldCallback(CSOUND *, int (*yieldCallback_)(CSOUND *)); 2133 2134 /** 2135 * Creates and starts a new thread of execution. 2136 * Returns an opaque pointer that represents the thread on success, 2137 * or NULL for failure. 2138 * The userdata pointer is passed to the thread routine. 2139 */ 2140 PUBLIC void *csoundCreateThread(uintptr_t (*threadRoutine)(void *), 2141 void *userdata); 2142 2143 /** 2144 * Returns the ID of the currently executing thread, 2145 * or NULL for failure. 2146 * 2147 * NOTE: The return value can be used as a pointer 2148 * to a thread object, but it should not be compared 2149 * as a pointer. The pointed to values should be compared, 2150 * and the user must free the pointer after use. 2151 */ 2152 PUBLIC void *csoundGetCurrentThreadId(void); 2153 2154 /** 2155 * Waits until the indicated thread's routine has finished. 2156 * Returns the value returned by the thread routine. 2157 */ 2158 PUBLIC uintptr_t csoundJoinThread(void *thread); 2159 /** 2160 * Creates and returns a monitor object, or NULL if not successful. 2161 * The object is initially in signaled (notified) state. 2162 */ 2163 PUBLIC void *csoundCreateThreadLock(void); 2164 2165 /** 2166 * Waits on the indicated monitor object for the indicated period. 2167 * The function returns either when the monitor object is notified, 2168 * or when the period has elapsed, whichever is sooner; in the first case, 2169 * zero is returned. 2170 * If 'milliseconds' is zero and the object is not notified, the function 2171 * will return immediately with a non-zero status. 2172 */ 2173 PUBLIC int csoundWaitThreadLock(void *lock, size_t milliseconds); 2174 2175 /** 2176 * Waits on the indicated monitor object until it is notified. 2177 * This function is similar to csoundWaitThreadLock() with an infinite 2178 * wait time, but may be more efficient. 2179 */ 2180 PUBLIC void csoundWaitThreadLockNoTimeout(void *lock); 2181 2182 /** 2183 * Notifies the indicated monitor object. 2184 */ 2185 PUBLIC void csoundNotifyThreadLock(void *lock); 2186 2187 /** 2188 * Destroys the indicated monitor object. 2189 */ 2190 PUBLIC void csoundDestroyThreadLock(void *lock); 2191 2192 /** 2193 * Creates and returns a mutex object, or NULL if not successful. 2194 * Mutexes can be faster than the more general purpose monitor objects 2195 * returned by csoundCreateThreadLock() on some platforms, and can also 2196 * be recursive, but the result of unlocking a mutex that is owned by 2197 * another thread or is not locked is undefined. 2198 * If 'isRecursive' is non-zero, the mutex can be re-locked multiple 2199 * times by the same thread, requiring an equal number of unlock calls; 2200 * otherwise, attempting to re-lock the mutex results in undefined 2201 * behavior. 2202 * Note: the handles returned by csoundCreateThreadLock() and 2203 * csoundCreateMutex() are not compatible. 2204 */ 2205 PUBLIC void *csoundCreateMutex(int isRecursive); 2206 2207 /** 2208 * Acquires the indicated mutex object; if it is already in use by 2209 * another thread, the function waits until the mutex is released by 2210 * the other thread. 2211 */ 2212 PUBLIC void csoundLockMutex(void *mutex_); 2213 2214 /** 2215 * Acquires the indicated mutex object and returns zero, unless it is 2216 * already in use by another thread, in which case a non-zero value is 2217 * returned immediately, rather than waiting until the mutex becomes 2218 * available. 2219 * Note: this function may be unimplemented on Windows. 2220 */ 2221 PUBLIC int csoundLockMutexNoWait(void *mutex_); 2222 2223 /** 2224 * Releases the indicated mutex object, which should be owned by 2225 * the current thread, otherwise the operation of this function is 2226 * undefined. A recursive mutex needs to be unlocked as many times 2227 * as it was locked previously. 2228 */ 2229 PUBLIC void csoundUnlockMutex(void *mutex_); 2230 2231 /** 2232 * Destroys the indicated mutex object. Destroying a mutex that 2233 * is currently owned by a thread results in undefined behavior. 2234 */ 2235 PUBLIC void csoundDestroyMutex(void *mutex_); 2236 2237 2238 /** 2239 * Create a Thread Barrier. Max value parameter should be equal to 2240 * number of child threads using the barrier plus one for the 2241 * master thread */ 2242 2243 PUBLIC void *csoundCreateBarrier(unsigned int max); 2244 2245 /** 2246 * Destroy a Thread Barrier. 2247 */ 2248 PUBLIC int csoundDestroyBarrier(void *barrier); 2249 2250 /** 2251 * Wait on the thread barrier. 2252 */ 2253 PUBLIC int csoundWaitBarrier(void *barrier); 2254 2255 2256 /** Creates a conditional variable */ 2257 PUBLIC void* csoundCreateCondVar(); 2258 2259 /** Waits up on a conditional variable and mutex */ 2260 PUBLIC void csoundCondWait(void* condVar, void* mutex); 2261 2262 /** Signals a conditional variable */ 2263 PUBLIC void csoundCondSignal(void* condVar); 2264 2265 /** Destroys a conditional variable */ 2266 PUBLIC void csoundDestroyCondVar(void* condVar); 2267 2268 /** 2269 * Waits for at least the specified number of milliseconds, 2270 * yielding the CPU to other threads. 2271 */ 2272 PUBLIC void csoundSleep(size_t milliseconds); 2273 2274 /** 2275 * If the spinlock is not locked, lock it and return; 2276 * if is is locked, wait until it is unlocked, then lock it and return. 2277 * Uses atomic compare and swap operations that are safe across processors 2278 * and safe for out of order operations, 2279 * and which are more efficient than operating system locks. 2280 * Use spinlocks to protect access to shared data, especially in functions 2281 * that do little more than read or write such data, for example: 2282 * 2283 * @code 2284 * static spin_lock_t lock = SPINLOCK_INIT; 2285 * csoundSpinLockInit(&lock); 2286 * void write(size_t frames, int* signal) 2287 * { 2288 * csoundSpinLock(&lock); 2289 * for (size_t frame = 0; i < frames; frame++) { 2290 * global_buffer[frame] += signal[frame]; 2291 * } 2292 * csoundSpinUnlock(&lock); 2293 * } 2294 * @endcode 2295 */ 2296 PUBLIC int csoundSpinLockInit(spin_lock_t *spinlock); 2297 2298 /** 2299 * Locks the spinlock 2300 */ 2301 PUBLIC void csoundSpinLock(spin_lock_t *spinlock); 2302 2303 /** 2304 * Tries the lock, returns CSOUND_SUCCESS if lock could be acquired, 2305 CSOUND_ERROR, otherwise. 2306 */ 2307 PUBLIC int csoundSpinTryLock(spin_lock_t *spinlock); 2308 2309 /** 2310 * Unlocks the spinlock 2311 */ 2312 PUBLIC void csoundSpinUnLock(spin_lock_t *spinlock); 2313 2314 2315 /** @}*/ 2316 /** @defgroup MISCELLANEOUS Miscellaneous functions 2317 * 2318 * @{ */ 2319 2320 /** 2321 * Runs an external command with the arguments specified in 'argv'. 2322 * argv[0] is the name of the program to execute (if not a full path 2323 * file name, it is searched in the directories defined by the PATH 2324 * environment variable). The list of arguments should be terminated 2325 * by a NULL pointer. 2326 * If 'noWait' is zero, the function waits until the external program 2327 * finishes, otherwise it returns immediately. In the first case, a 2328 * non-negative return value is the exit status of the command (0 to 2329 * 255), otherwise it is the PID of the newly created process. 2330 * On error, a negative value is returned. 2331 */ 2332 PUBLIC long csoundRunCommand(const char * const *argv, int noWait); 2333 2334 /** 2335 * Initialise a timer structure. 2336 */ 2337 PUBLIC void csoundInitTimerStruct(RTCLOCK *); 2338 2339 /** 2340 * Return the elapsed real time (in seconds) since the specified timer 2341 * structure was initialised. 2342 */ 2343 PUBLIC double csoundGetRealTime(RTCLOCK *); 2344 2345 /** 2346 * Return the elapsed CPU time (in seconds) since the specified timer 2347 * structure was initialised. 2348 */ 2349 PUBLIC double csoundGetCPUTime(RTCLOCK *); 2350 2351 /** 2352 * Return a 32-bit unsigned integer to be used as seed from current time. 2353 */ 2354 PUBLIC uint32_t csoundGetRandomSeedFromTime(void); 2355 2356 /** 2357 * Set language to 'lang_code' (lang_code can be for example 2358 * CSLANGUAGE_ENGLISH_UK or CSLANGUAGE_FRENCH or many others, 2359 * see n_getstr.h for the list of languages). This affects all 2360 * Csound instances running in the address space of the current 2361 * process. The special language code CSLANGUAGE_DEFAULT can be 2362 * used to disable translation of messages and free all memory 2363 * allocated by a previous call to csoundSetLanguage(). 2364 * csoundSetLanguage() loads all files for the selected language 2365 * from the directory specified by the CSSTRNGS environment 2366 * variable. 2367 */ 2368 PUBLIC void csoundSetLanguage(cslanguage_t lang_code); 2369 2370 /** 2371 * Get pointer to the value of environment variable 'name', searching 2372 * in this order: local environment of 'csound' (if not NULL), variables 2373 * set with csoundSetGlobalEnv(), and system environment variables. 2374 * If 'csound' is not NULL, should be called after csoundCompile(). 2375 * Return value is NULL if the variable is not set. 2376 */ 2377 PUBLIC const char *csoundGetEnv(CSOUND *csound, const char *name); 2378 2379 /** 2380 * Set the global value of environment variable 'name' to 'value', 2381 * or delete variable if 'value' is NULL. 2382 * It is not safe to call this function while any Csound instances 2383 * are active. 2384 * Returns zero on success. 2385 */ 2386 PUBLIC int csoundSetGlobalEnv(const char *name, const char *value); 2387 2388 /** 2389 * Allocate nbytes bytes of memory that can be accessed later by calling 2390 * csoundQueryGlobalVariable() with the specified name; the space is 2391 * cleared to zero. 2392 * Returns CSOUND_SUCCESS on success, CSOUND_ERROR in case of invalid 2393 * parameters (zero nbytes, invalid or already used name), or 2394 * CSOUND_MEMORY if there is not enough memory. 2395 */ 2396 PUBLIC int csoundCreateGlobalVariable(CSOUND *, 2397 const char *name, size_t nbytes); 2398 2399 /** 2400 * Get pointer to space allocated with the name "name". 2401 * Returns NULL if the specified name is not defined. 2402 */ 2403 PUBLIC void *csoundQueryGlobalVariable(CSOUND *, const char *name); 2404 2405 /** 2406 * This function is the same as csoundQueryGlobalVariable(), except the 2407 * variable is assumed to exist and no error checking is done. 2408 * Faster, but may crash or return an invalid pointer if 'name' is 2409 * not defined. 2410 */ 2411 PUBLIC void *csoundQueryGlobalVariableNoCheck(CSOUND *, const char *name); 2412 2413 /** 2414 * Free memory allocated for "name" and remove "name" from the database. 2415 * Return value is CSOUND_SUCCESS on success, or CSOUND_ERROR if the name is 2416 * not defined. 2417 */ 2418 PUBLIC int csoundDestroyGlobalVariable(CSOUND *, const char *name); 2419 2420 /** 2421 * Run utility with the specified name and command line arguments. 2422 * Should be called after loading utility plugins. 2423 * Use csoundReset() to clean up after calling this function. 2424 * Returns zero if the utility was run successfully. 2425 */ 2426 PUBLIC int csoundRunUtility(CSOUND *, const char *name, 2427 int argc, char **argv); 2428 2429 /** 2430 * Returns a NULL terminated list of registered utility names. 2431 * The caller is responsible for freeing the returned array with 2432 * csoundDeleteUtilityList(), however, the names should not be 2433 * changed or freed. 2434 * The return value may be NULL in case of an error. 2435 */ 2436 PUBLIC char **csoundListUtilities(CSOUND *); 2437 2438 /** 2439 * Releases an utility list previously returned by csoundListUtilities(). 2440 */ 2441 PUBLIC void csoundDeleteUtilityList(CSOUND *, char **lst); 2442 2443 /** 2444 * Get utility description. 2445 * Returns NULL if the utility was not found, or it has no description, 2446 * or an error occured. 2447 */ 2448 PUBLIC const char *csoundGetUtilityDescription(CSOUND *, 2449 const char *utilName); 2450 2451 /** 2452 * Simple linear congruential random number generator: 2453 * (*seedVal) = (*seedVal) * 742938285 % 2147483647 2454 * the initial value of *seedVal must be in the range 1 to 2147483646. 2455 * Returns the next number from the pseudo-random sequence, 2456 * in the range 1 to 2147483646. 2457 */ 2458 PUBLIC int csoundRand31(int *seedVal); 2459 2460 /** 2461 * Initialise Mersenne Twister (MT19937) random number generator, 2462 * using 'keyLength' unsigned 32 bit values from 'initKey' as seed. 2463 * If the array is NULL, the length parameter is used for seeding. 2464 */ 2465 PUBLIC void csoundSeedRandMT(CsoundRandMTState *p, 2466 const uint32_t *initKey, uint32_t keyLength); 2467 2468 /** 2469 * Returns next random number from MT19937 generator. 2470 * The PRNG must be initialised first by calling csoundSeedRandMT(). 2471 */ 2472 PUBLIC uint32_t csoundRandMT(CsoundRandMTState *p); 2473 2474 #endif /* !CSOUND_CSDL_H */ 2475 2476 /* typedefs, macros, and interface functions for configuration variables */ 2477 #include "cfgvar.h" 2478 /* message attribute definitions for csoundMessageS() and csoundMessageV() */ 2479 #include "msg_attr.h" 2480 /* macro definitions for Csound release, and API version */ 2481 #include "version.h" 2482 2483 /** 2484 * Create circular buffer with numelem number of elements. The 2485 * element's size is set from elemsize. It should be used like: 2486 *@code 2487 * void *rb = csoundCreateCircularBuffer(csound, 1024, sizeof(MYFLT)); 2488 *@endcode 2489 */ 2490 PUBLIC void *csoundCreateCircularBuffer(CSOUND *csound, 2491 int numelem, int elemsize); 2492 2493 /** 2494 * Read from circular buffer 2495 * @param csound This value is currently ignored. 2496 * @param circular_buffer pointer to an existing circular buffer 2497 * @param out preallocated buffer with at least items number of elements, where 2498 * buffer contents will be read into 2499 * @param items number of samples to be read 2500 * @returns the actual number of items read (0 <= n <= items) 2501 */ 2502 PUBLIC int csoundReadCircularBuffer(CSOUND *csound, void *circular_buffer, 2503 void *out, int items); 2504 2505 /** 2506 * Read from circular buffer without removing them from the buffer. 2507 * @param circular_buffer pointer to an existing circular buffer 2508 * @param out preallocated buffer with at least items number of elements, where 2509 * buffer contents will be read into 2510 * @param items number of samples to be read 2511 * @returns the actual number of items read (0 <= n <= items) 2512 */ 2513 PUBLIC int csoundPeekCircularBuffer(CSOUND *csound, void *circular_buffer, 2514 void *out, int items); 2515 2516 /** 2517 * Write to circular buffer 2518 * @param csound This value is currently ignored. 2519 * @param p pointer to an existing circular buffer 2520 * @param inp buffer with at least items number of elements to be written into 2521 * circular buffer 2522 * @param items number of samples to write 2523 * @returns the actual number of items written (0 <= n <= items) 2524 */ 2525 PUBLIC int csoundWriteCircularBuffer(CSOUND *csound, void *p, 2526 const void *inp, int items); 2527 /** 2528 * Empty circular buffer of any remaining data. This function should only be 2529 * used if there is no reader actively getting data from the buffer. 2530 * @param csound This value is currently ignored. 2531 * @param p pointer to an existing circular buffer 2532 */ 2533 PUBLIC void csoundFlushCircularBuffer(CSOUND *csound, void *p); 2534 2535 /** 2536 * Free circular buffer 2537 */ 2538 PUBLIC void csoundDestroyCircularBuffer(CSOUND *csound, void *circularbuffer); 2539 2540 /** 2541 * Platform-independent function to load a shared library. 2542 */ 2543 PUBLIC int csoundOpenLibrary(void **library, const char *libraryPath); 2544 2545 /** 2546 * Platform-independent function to unload a shared library. 2547 */ 2548 PUBLIC int csoundCloseLibrary(void *library); 2549 2550 /** 2551 * Platform-independent function to get a symbol address in a shared library. 2552 */ 2553 PUBLIC void *csoundGetLibrarySymbol(void *library, const char *symbolName); 2554 2555 2556 /** @}*/ 2557 2558 #ifdef SWIGPYTHON 2559 csoundGetInstance(int64_t obj)2560 PUBLIC CSOUND *csoundGetInstance(int64_t obj){ return (CSOUND *)obj; } 2561 2562 #endif 2563 2564 2565 #ifdef SOME_FINE_DAY /* these functions are now deprecated */ 2566 2567 /** 2568 * Returns a pointer to the requested interface, if available, in the 2569 * interface argument, and its version number, in the version argument. 2570 * Returns 0 for success. 2571 */ 2572 2573 PUBLIC int csoundQueryInterface(const char *name, 2574 void **iface, int *version); 2575 2576 2577 /** 2578 * Control values are specified by a 'channelName' string. 2579 * Note that the 'invalue' & 'outvalue' channels can be specified by 2580 * either a string or a number. If a number is specified, it will be 2581 * converted to a string before making the callbacks to the external 2582 * software. 2583 */ 2584 2585 /** 2586 * Called by external software to set a function for Csound to 2587 * fetch input control values. The 'invalue' opcodes will 2588 * directly call this function. If 'channelName' starts with a 2589 * '$', then 'invalue' opcode is expecting a C string, to be copied 2590 * to 'value', with maximum size csoundGetChannelDatasize(). 2591 */ 2592 PUBLIC void csoundSetInputValueCallback(CSOUND *, 2593 void (*inputValueCalback_)(CSOUND *, 2594 const char *channelName, 2595 MYFLT *value)); 2596 2597 /** 2598 * Called by external software to set a function for Csound to 2599 * send output control values. The 'outvalue' opcodes will 2600 * directly call this function. If 'channelName' starts with a 2601 * '$', then the 'outvalue' opcode is sending a string appended 2602 * to channelName in the format: "$channelName$stringOutput". 2603 * and 'value' will be the index number into 'channelName' where 2604 * the stringOutput begins. 2605 */ 2606 PUBLIC void csoundSetOutputValueCallback(CSOUND *, 2607 void (*outputValueCalback_)(CSOUND *, 2608 const char *channelName, 2609 MYFLT value)); 2610 2611 /** 2612 * Sets callback function to be called by the opcodes 'chnsend' and 2613 * 'chnrecv'. Should be called before csoundCompile(). 2614 * The callback function takes the following arguments: 2615 * CSOUND *csound 2616 * Csound instance pointer 2617 * const char *channelName 2618 * the channel name 2619 * MYFLT *channelValuePtr 2620 * pointer to the channel value. Control channels are a single MYFLT 2621 * value, while audio channels are an array of csoundGetKsmps(csound) 2622 * MYFLT values. In the case of string channels, the pointer should be 2623 * cast to char *, and points to a buffer of 2624 * csoundGetChannelDatasize() bytes 2625 * int channelType 2626 * bitwise OR of the channel type (CSOUND_CONTROL_CHANNEL, 2627 * CSOUND_AUDIO_CHANNEL, or CSOUND_STRING_CHANNEL; use 2628 * channelType & CSOUND_CHANNEL_TYPE_MASK to extract the channel 2629 * type), and either CSOUND_INPUT_CHANNEL or CSOUND_OUTPUT_CHANNEL 2630 * to indicate the direction of the data transfer 2631 * The callback is not preserved on csoundReset(). 2632 */ 2633 PUBLIC void csoundSetChannelIOCallback(CSOUND *, 2634 CsoundChannelIOCallback_t func); 2635 2636 /** 2637 * Senses input events, and performs one control sample worth (ksmps) of 2638 * audio output. 2639 * Note that csoundCompile() or csoundCompileOrc(), 2640 * csoundReadScore(), csoundStart() must be called first. 2641 * Performs audio whether or not the Csound score has finished. 2642 * Enables external software to control the execution of Csound, 2643 * and to synchronize performance with audio input and output. 2644 */ 2645 PUBLIC int csoundPerformKsmpsAbsolute(CSOUND *); 2646 #endif 2647 2648 2649 #ifdef __cplusplus 2650 } 2651 #endif 2652 2653 #endif /* CSOUND_H */ 2654