SCORE OPCODES

by Gabriel Maldonado
http://csounds.com/maldonado


LOOPS

{ - start of a loop

} - end of a loop

Syntax:

{  num NN

   ...... body........

}

Score loops are a very powerful tool. Derived by repeats (r opcode), they allow to define any parameter, and the score events inside the loop are not separated by a section termination in each iteration. So it is possible to implement overlapping loops. Loops can be nested. The syntax is similar to that of the repeats: the macro $NN is incremented in each iteration (notice that, differently from repeats, it starts with a zero value); num argument must be set to the number of iterations.

NB: exponential ramp symbol has been changed to '(' or ')' in order to allow curly-brace characters to be used for loops.

EXAMPLE:

{ 10 nn
	i1	[$nn/2]  .5  [$Line(10' $nn ' 10000' 4000)]  [$Line(10'$nn'440'110)]
	{ 5 bb
		i1 [$nn/2+$bb/10] .1 [(1+$nn/4)*$Line(10 ' $bb' 2000' 500)] [$Line(10'  $bb' 400' 600)]
	}
}


SCORE TABLES

F - score function tables

Syntax:

F p1 p2 p3 p4 ...

This causes a GEN subroutine to place values in a stored function table for use by instruments.

N.B. In this case the function tables are created before score processing, differently from f statement. The syntax and the gen routines used by F opcode are identical to those of f statement. Tables created by F opcode are intended to be used together with T score arithmetic operator (see below).


NESTED MACROS (new syntax)

Now macros can be nested (both in orchestra and score), that is a  previously defined macro can be called from inside another macro definition. When using nested macros, it is recommended to use different names for arguments in the caller and in the target macros to avoid  unpredictable conflicts.
To enable this feature I had to do a small change in macro argument syntax: instead of using a '#' character, an apostrophe character is required in order to separate macro arguments:

OLD SYNTAX:

#define  PLUTO(mikey#minnie#donald)#....body....#         ; old macro definition

$PLUTO(1#2#3)        ;old macro call

NEW SYNTAX (nested macros):

#define  PLUTO( mikey '  minnie '  donald ) # ....body.... #       ; new macro definition

;nested macro definition. Notice that the argument names are changed
#define PIPPO( mik ' min ' don) #      
     $PLUTO( 2*$mik '  2+$min '  3 )
     $PLUTO( 5 '   8 '   1 )            
     $PLUTO( $mik,$min,3 )      
     $PLUTO( 1 '   2 '  $don )        
     $PLUTO( 4 '   5 '   6 )            
# ;end of macro
$PIPPO( 1' 5' 8 )   ; macro call

It is now possible to comment macros (before it generated errors):

;$PIPPO(1'2'3)

 or

/*
$PIPPO(1'2'3)
*/

Comments (both old assebler style ';' and new C-language style '/* ...  */') are handled in a special way in macros. Inside macro body you are allowed to put only old style comments ( ';'). If you intend to suppress an entire macro without erasing it physically, you can comment it using C-style comments externally  ('/* ...  */').

Maximum number of macro arguments has been raised to 200 (before 5)

N.B. underscore character '_'  has a special purpose in macros (it allows to define prefixes or suffixes  of words in macro body). Don't use underscore character in macro names or in macro arguments (or errors will occurr). You are allowed to use underscore in the body of macros in any case, instead.


SCORE MACRO ARITHMETIC INFIX OPERATORS

SCORE TABLES

T - retrieves a value from a score function table.

syntax:

(TabNum T  TabIndex)

TabNum - table number
TabIndex - absolute index of table element.

N.B. the unusual infix syntax can be transformed into a more familiar syntax by means of macros:

#define Table(tabnum'index) # (($tabnum) T ($index)) #

so you can call the $Table( ) macro with the classic function call syntax:

$Table(num' element)


RANDOM NUMBER OPERATOR

R - retrieves a  pseudo random value

syntax:

(amp  R  seed)

The operand amp is an amplitude factor that sets the range of random values from zero to amp itself.
The operand seed allows the user to change the initial seed of the pseudo random sequence. When seed is set to a non-zero value, R operator sets the seed, while with seed = 0 it returns a normal random value. When seed is set to -1 the seed of pseudo random sequence is obtained by the current timer value of the computer, allowing a different pseudo random sequence each time Csound is run.

N.B. the unusual infix syntax can be transformed into a more familiar syntax by means of macros:

#define RndSeed(seed) # (1 R ($seed)) #
#define Rand(min'max) # ( ($min) + ((($max)-($min)) R 0)  ) #

In these examples $RndSeed( ) macro sets the seed, while $Rand( ) retrives a random value inside the  min-max interval.


POWER OPERATOR

^  - retrieves the power

syntax:

(a  ^  b)

raises number a to the b power

Here are two example of macros very useful when using loops or repeats:

#define Expon(stepnum ' var ' a' b) # ( ($a) *(((($b)/($a))^(1/(($steps)-1)))^($var))  ) #
#define Expon1(stepnum ' var ' a' b) # ( ($a) *(((($b)/($a))^(1/(($steps)-1)))^($var-1)) ) #

Notice that macro $Expon is provided for loops (where macro index $var starts from zero), while $Expon1 is thought for repeats, where $var starts from 1.

For reasons of completeness  here are the  corresponding linear macros:

#define  Line(steps 'var'a'b) # ( ($a) +  (($b)-($a))*(($var))/(($steps)-1)  ) #
#define  Line1(steps'var'a'b) # ( ($a) +  (($b)-($a))*(($var-1))/(($steps)-1)  ) #

MODULUS OPERATOR

% - modulus operator

syntax:

(a  %  b)

retrives a MOD b