#define — Defines a macro.
Macros are textual replacements which are made in the orchestra as it is being read. The macro system in Csound is a very simple one, and uses the characters # and $ to define and call macros. This can save typing, and can lead to a coherent structure and consistent style. This is similar to, but independent of, the macro system in the score language.
#define NAME -- defines a simple macro. The name of the macro must begin with a letter and can consist of any combination of letters and numbers. Case is significant. This form is limiting, in that the variable names are fixed. More flexibility can be obtained by using a macro with arguments, described below.
#define NAME(a' b' c') -- defines a macro with arguments. This can be used in more complex situations. The name of the macro must begin with a letter and can consist of any combination of letters and numbers. Within the replacement text, the arguments can be substituted by the form: $A. In fact, the implementation defines the arguments as simple macros. There may be up to 5 arguments, and the names may be any choice of letters. Remember that case is significant in macro names.
# replacement text # -- The replacement text is any character string (not containing a #) and can extend over mutliple lines. The replacement text is enclosed within the # characters, which ensure that additional characters are not inadvertently captured.
Some care is needed with textual replacement macros, as they can sometimes do strange things. They take no notice of any meaning, so spaces are significant. This is why, unlike the C programming language, the definition has the replacement text surrounded by # characters. Used carefully, this simple macro system is a powerful concept, but it can be abused.
Here is a simple example of the defining a macro. It uses the file define.csd.
Example 14. Simple example of the define macro.
See the sections Real-time Audio and Command Line Flags for more information on using command line flags.
<CsoundSynthesizer> <CsOptions> ; Select audio/midi flags here according to platform ; Audio out Audio in No messages -odac -iadc -d ;;;RT audio I/O ; For Non-realtime ouput leave only the line below: ; -o define.wav -W ;;; for file output any platform </CsOptions> <CsInstruments> ; Initialize the global variables. sr = 44100 kr = 4410 ksmps = 10 nchnls = 1 ; Define the macros. #define VOLUME #5000# #define FREQ #440# #define TABLE #1# ; Instrument #1 instr 1 ; Use the macros. ; This will be expanded to "a1 oscil 5000, 440, 1". a1 oscil $VOLUME, $FREQ, $TABLE ; Send it to the output. out a1 endin </CsInstruments> <CsScore> ; Define Table #1 with an ordinary sine wave. f 1 0 32768 10 1 ; Play Instrument #1 for two seconds. i 1 0 2 e </CsScore> </CsoundSynthesizer>
Its output should include lines like this:
Macro definition for VOLUME Macro definition for CPS Macro definition for TABLE
Here is an example of the defining a macro with arguments. It uses the file define_args.csd.
Example 15. Example of the define macro with arguments.
<CsoundSynthesizer> <CsOptions> ; Select audio/midi flags here according to platform ; Audio out Audio in No messages -odac -iadc -d ;;;RT audio I/O ; For Non-realtime ouput leave only the line below: ; -o define_args.wav -W ;;; for file output any platform </CsOptions> <CsInstruments> ; Initialize the global variables. sr = 44100 kr = 4410 ksmps = 10 nchnls = 1 ; Define the oscillator macro. #define OSCMACRO(VOLUME'FREQ'TABLE) #oscil $VOLUME, $FREQ, $TABLE# ; Instrument #1 instr 1 ; Use the oscillator macro. ; This will be expanded to "a1 oscil 5000, 440, 1". a1 $OSCMACRO(5000'440'1) ; Send it to the output. out a1 endin </CsInstruments> <CsScore> ; Define Table #1 with an ordinary sine wave. f 1 0 32768 10 1 ; Play Instrument #1 for two seconds. i 1 0 2 e </CsScore> </CsoundSynthesizer>
Its output should include lines like this:
Macro definition for OSCMACRO
New in Csound 5.04 are predefined Math Constant Macros. The values defined are those found in the C header math.h, and are automatically defined when Csound starts and available for use in orchestras.
Macro | Value | Equivalent to |
---|---|---|
$M_E | 2.7182818284590452354 | e |
$M_LOG2E | 1.4426950408889634074 | log_2(e) |
$M_LOG10E | 0.43429448190325182765 | log_10(e) |
$M_LN2 | 0.69314718055994530942 | log_e(2) |
$M_LN10 | 2.30258509299404568402 | log_e(10) |
$M_PI | 3.14159265358979323846 | pi |
$M_PI_2 | 1.57079632679489661923 | pi/2 |
$M_PI_4 | 0.78539816339744830962 | pi/4 |
$M_1_PI | 0.31830988618379067154 | 1/pi |
$M_2_PI | 0.63661977236758134308 | 2/pi |
$M_2_SQRTPI | 1.12837916709551257390 | 2/sqrt(pi) |
$M_SQRT2 | 1.41421356237309504880 | sqrt(2) |
$M_SQRT1_2 | 0.70710678118654752440 | 1/sqrt(2) |