Release Notes for 3.50
======================

These are the release notes for version 3.50.  This accumulates a
number of changes which have been released in bits, but there are even
more here than previously released.

It incorporates significant bodies of code from Gabriel Maldonado and
hans Mikelson, with contributions from Richard Boulanger, V.Lazzarini,
Greg Sulliven, rasmus ekman, matt ingalls, Ed Hall, and many others
who assisted in identifying bugs etc. (I really should maintain
records of them all, but they know who they are I hope).


Bug Fixes
---------

Pow now available again.
Internal changes to parser to make fewer calls to strcmp
Corrections to rand in a-rate case and 16 bit randoms
Two bugs in extending labels and goto tables corrected
Minor bug in extending instrument numbers fixed

Language Changes
----------------

hetro had a wrong constant which would give rise to a little noise.

If the incorrect out opcode is used it now attempts to correct to the
correct one, which is not necessarily correct.

new names dumpk rather than kdump introduced. 

kon renamed midion

kfilter2 renamed filter2 (still not sure it works though)

The opcodes rand randi and randh take an additional, optional argument
which if non zero gives a 31bit random nuber rather than the 16bit one.

Rising to a power is available in expressions with the ^ operator.
use with some caution as I am not sure that the precidence is correct.

An internal changes has changed the conditional compilation flag for
the Ingalls' port from __MWERKS__ to macintosh; this should help the
BeOS port.

The single file .csd input has been extended for all command-line
versions, and possibly for Windows.  It can not decode additional
parameters.

Id a file .csoundrc exists, it is read to set parameters first, which
can be overridden.  It used the .csd form so options are written as on
the command line, with optional newlines at appropriate places.  It
does not set orc/sco names (as far as i can understand it)

Opcode Fixes
------------

sndwarp had bugs on Linux

rand, randh and randi now take an additional operand, which if
non-zero use a better randon number generator

bug in ntrpol fixed

MIDI on Linux may work, or may not....

Many changes to the pitchbend opcodes

moogvcf and rezzy can accept a-rate parameters, and moogvcf takes an
optional scaling factor

foscil/foscili can take a-rate amplitude and frequency

biquad has an additional optional argument, which if non zero skips
initialisation. 


New Opcodes 
-----------

schedule -- schedule an instrument event

schedwhen -- conditional scheduling

lfo -- Low Frequency Oscilator with 6 shapes

midion2 -- MIDI turnon (G.Maldonado)

midiin --  (G.Maldonado)

midiout --  (G.Maldonado)

nrpn --  (G.Maldonado)

cpstmid --  (G.Maldonado)

streson -- string resonator (V.Lazzarini)

mod opcodes -- to complete arithmetic operations

slider8, slider8f, islider8
slider16, slider16f, islider16
slider32, slider32f, islider32
slider64, slider64f, islider64
s16b14, is16b14, s32b14, is32b14  -- MIDI slider controls (G.Maldonado)

vco -- (Hans Mikelson)

planet -- (Hans Mikelson)

distort1 -- (Hans Mikelson)

pareq -- Implementation of Zoelzer's Parmentric Equalizer Filters (Hans Mikelson)

deltapn -- (Hans Mikelson)

Experimental opcodes:
--------------------
oscil3 -- Just like oscili but with cubic interpolation
foscil3
losil3
table3
itable3
deltap3
vdelay3

Other Changes:
-------------

use of kdump or kon, while still allowed gives a message about
deprecated opcodes.

Windows GUI Changes
-------------------

None i think

------------------------------------------------------------------------
==John ff
  1999 Orthodox Christmas
========================================================================

schedule, schedwhen

	schedule	inst, iwhen, idur, ....
	schedwhen	ktrigger, kinst, kwhen, kdur, ....

PERFORMANCE

schedule adds a new score event.  The arguments are the same as in a
score.  The when time (p2) is measured from the time of this event.

If the duration is zero or negative the new event is of MIDI type, and
inherits the release sub-event from the scheduling instruction.

In the case of schedwhen the event is only scheduled when the krate
value ktrigger is first non-zero.

Examples:

;; Double hit and 1sec separation
instr 1
      schedule	2,  1, 0.5, p4, p5
a1    shaker	p4, 60, 0.999, 0, 100, 0
      out	a1
endin

instr 2
a1    marimba   p4, cpspch(p5), p6, p7, 2, 6.0, 0.05, 1, 0.1
      out       a1
endin 

instr 3 
kr    table	kr, 1
      schedwhen	kr, 1, 0.25, 1, p4, p5
endin
------------------------------------------------------------------------

lfo

kr	lfo		kamp, kcps[, itype]
ar	lfo		kamp, kcps[, itype]

DESCRIPTION

A LFO of various shapes

INITALIZATION

itype -- determine the form of the oscilator
  (default) 0:	sine
            1:  triangles
	    2:  square (biplar)
	    3:  square (unipolar)
	    4:  saw-tooth
	    5:  saw-tooth(down)

The sine wave is implemented as a 4096 table and linear
interpolation.  The others are calculated.

PERFORMANCE

ar, kr - output signal
kamp - amplitude
kcps - frequency of oscilator

EXAMPLE:
instr 1
kp    lfo	10, 5, 4
ar    oscil	p4, p5+kp, 1
      out	ar
endin

------------------------------------------------------------------------
minion2

        midion2    kchn, knum, kvel, ktrig

DESCRIPTION

sends note on and off messages to the midi out port when triggered by a 
value different than zero.


PERFORMANCE

kchn - midi channel
knum - midi note number
kvel - note velocity
ktrig - trigger input signal (normally 0)

Similary to 'midion', this opcode sends note-on and note-off messages
to the midi out port, but only when ktrig is different than zero. This
opcode is thinked to work toghether with the output of the 'trigger' opcode.

(G.Maldonado)

------------------------------------------------------------------------
midiin

kstatus, kchan, kdata1, kdata2          midiin

DESCRIPTION
returns a generic midi message received by the midi in port


PERFORMANCE
kstatus - the type of midi message. Can be:
                128 (note off),
                144 (note on),
                160 (polyphonic aftertouch), 
                176 (control change),
                192 (program change), 
                208 (channel aftertouch),
                224 (pitch bend)
                or 0 if no midi message are pending in the MIDI IN buffer.

kchan - midi channel (1-16)
kdata1, kdata2 - message-dependent data values

midiin has no input arguments, because it reads at the midi in port
implicitly.  It works at k-rate. Normally (i.e. when no messages are
pending) kstatus is zero, only each time midi data are present in the
midi in buffer, kstatus is set to the type of the relative messages.

(G.Maldonado)
------------------------------------------------------------------------
midiout

        midiout         kstatus, kchan, kdata1, kdata2

DESCRIPTION
sends a generic midi message to the midi out port

PERFORMANCE
kstatus - the type of midi message. Can be:
                128 (note off),
                144 (note on),
                160 (polyphonic aftertouch), 
                176 (control change),
                192 (program change), 
                208 (channel aftertouch),  
                224 (pitch bend)
                or 0 when no midi messages must be sent to the MIDI OUT port.
kchan - midi channel (1-16)
kdata1, kdata2 - message-dependent data values

midiout has not output arguments, because it sends the message to the
midi out port implicitly.  It works at k-rate. It sends a midi message
only when kstatus is different than zero. 
Warning! Normally kstatus should be set to 0, only when the user
intend to send a midi message, it can be set to the corresponding
message type number.

(G.Maldonado)
------------------------------------------------------------------------
nrpn

        nrpn    kchan, kparmnum, kparmvalue

DESCRIPTION

sends a nprn (Non Registered Parameter Number) message to the midi out port 
each time one of the input arguments changes.


PERFORMANCE

kchan - midi channel
kparmnum - number of NRPN parameter
kparmvalue - value of NRPN parameter


This opcode sends new message when the MIDI translated value of one of
the input arguments changes. It operates at k-rate. Useful with the
midi instruments that recognize NRPNs (for example with the newest
sound-cards with internal midi synthesizer such as SB AWE32, AWE64,
GUS etc. in which each patch parameter can be changed during the
performance via NRPN)

(G.Maldonado)
------------------------------------------------------------------------
cpstmid

icps    cpstmid  ifn

INITIALIZATION

ifn - function table containing the parameters 
      (numgrades, interval, basefreq, basekeymidi) and
      the tuning ratios.

(init rate only)

This unit is similar to cpsmidi, but allows fully customized
micro-tuning scales.  It requires five parameters, the first ifn is
the function table number of the tuning ratios, and the other
parameters must be stored in the function tables itself.  The function
table ifn should be generated by the GEN2 and the first four values
stored in this function are: numgrades (the number of grades of the
micro-tuning scale), interval (the frequency range covered before
repeating the grade ratios, for example 2 for one octave, 1.5 for a
fift etcetera), basefreq (the base frequency of the scale in cps),
basekeymidi (the midi-note-number to which to assign the basefreq
unmodified). 

After these four values, the user can begin to insert the tuning
ratios.  For example, for a standard 12-grade scale with the
base-frequency of 261 cps assigned to the key-number 60, the
corresponding f-statement in the score to generate the table should
be:


;       numgrades     basefreq               tuning-ratios (eq.temp) ..
.....   
;            nterval         basekeymidi       
f1 0 64 -2 12 2   261    60   1  1.059463094359  1.122462048309  1.189207115003 ..etc...  


Another example with a 24-grade scale with a base frequency 
of 440 assigned to the key-number 48, and a repetition interval of 1.5:


;        numgrades        basefreq               tuning-ratios .......   
;                 interval         basekeymidi       
f1 0 64 -2   24      1.5     440        48        1   1.01  1.02  1.03   ..etc...  

(G.Maldonado)
------------------------------------------------------------------------
ar   streson  asig, kfr, ifdbgain

An audio signal is modified by an string resonator with variable
fundamental frequency.

INITIALIZATION

ifdbgain - feedback gain, between 0 and 1, of the internal
           delay line. A value close to 1 creates a slower decay and
           a more pronounced resonance. Small values may leave the
           input signal unaffected. Depending on the filter frequency,
           typical values are > .9.


PERFORMANCE

streson passes the input asig through a network composed of comb,
low-pass and all-pass filters, similar to the one used in some
versions of the Karplus-Strong algorythm, creating a string resonator
effect. The fundamental frequency of the "string" is controled by
the k-rate variable kfr.This opcode can be used to simulate sympathetic
resonances to an input signal.

streson is an adaptation of the StringFlt object of the SndObj Sound
Object Library developed by the author.

Victor Lazzarini
Music Department
National University of Ireland, Maynooth
Maynooth Co.Kildare
Ireland
------------------------------------------------------------------------
Expression:

kr =	ka % kb
ar =	ka % ab
ar =	aa % kb
ar =	aa % ab

PERFORMANCE

Returns the valus a reduced by b, so the result in absolute value that
the absoute value of b, by repeated subtraction.  This is the same as
a modulus function in the integer case.

------------------------------------------------------------------------

ar vco kamp, kfqc, iwave, kpw, isine, imaxd

Implementation of an band limited analog modeled oscillator based on
integration of band limited impulses.

Performance

vco can be used to simulate a variety of analog wave forms.

kamp determines the amplitude, kfqc is the frequency of the wave,

iwave determines the waveform 1 = sawtooth, 2 = Square/PWM, 3 = triangle/Saw
Ramp

kpw determines the pulse width when iwave is set to 2 and determines
Saw/Ramp character when iwave is set to 3. The value of kpw should be
between 0 and 1. A value of .5 will generate a square wave or a triangle
wave depending on iwave.

isine should be the number of a stored sine wave table.

imaxd is the maximum delay time. A time of 1/ifqc may be required for the
pwm and triangle waveform. To bend the pitch down this value must be as
large as 1/(minimum frequency).

Example

instr 10
  idur = p3 ; Duration
  iamp = p4 ; Amplitude
  ifqc = cpspch(p5) ; Frequency
  iwave = p6 ; Selected wave form 1=Saw, 2=Square/PWM, 3=Tri/Saw-Ramp-Mod
  isine = 1
  imaxd = 1/ifqc*2 ; Allows pitch bend down of two octaves
  kpw1 oscil .25, ifqc/200, 1
  kpw = kpw1 + .5
  asig vco iamp, ifqc, iwave, kpw, 1, imaxd
  outs asig, asig ; Ouput and amplification
endin

f1 0 65536 10 1
; Sta Dur Amp Pitch Wave
i10 0 2 20000 5.00 1
i10 + . . . 2
i10 . . . . 3
i10 . 2 20000 7.00 1
i10 . . . . 2
i10 . . . . 3
i10 . 2 20000 9.00 1
i10 . . . . 2
i10 . . . . 3
i10 . 2 20000 11.00 1
i10 . . . . 2
i10 . . . . 3
Author

Hans Mikelson

December 1998
------------------------------------------------------------------------

aout distort1 asig, kpregain, kpostgain, kshape1, kshape2

Implementation of modified hyperbolic tangent distortion.

Performance

distort1 can be used to generate wave shaping distortion based on a
modification of the tanh function.

       exp(asig * (pregain + shape1)) - exp(asig*(pregain+shape2))
aout = -----------------------------------------------------------
       exp(asig*pregain)              + exp(-asig*pregain)

asig is the input signal.

kpregain determines the amount of gain applied to the signal before
waveshaping. A value of 1 gives slight distortion.

kpostgain determines the amount of gain applied to the signal after
waveshaping.

kshape1 determines the shape of the positive part of the curve. A value of
zero gives a flat clip, small positive values give sloped shaping.

kshape2 determines the shape of the negative part of the curve.

Example

gadist  init    0

        instr   1
iamp    =       p4
ifqc    =       cpspch(p5)
asig    pluck   iamp, ifqc, ifqc, 0, 1
gadist  =       gadist + asig
        endin

        instr   50
kpre    init    p4
kpost   init    p5
kshap1  init    p6
kshap2  init    p7
aout    distort1 gadist, kpre, kpost, kshap1, kshap2
        outs    aout, aout
gadist  =       0
        endin

;   Sta  Dur  Amp    Pitch
i1  0.0  3.0  10000  6.00
i1  0.5  2.5  10000  7.00
i1  1.0  2.0  10000  7.07
i1  1.5  1.5  10000  8.00

;   Sta  Dur  PreGain PostGain Shape1 Shape2
i50 0    3    2       1        0      0
Author

Hans Mikelson
December 1998

PS Name chosen to avoid clash with XTC's distort opcode
------------------------------------------------------------------------
outx, outy, outz planet kmass1, kmass2, ksep, ix, iy, iz, ivx, ivy, ivz,
idelta, ifriction

Signal generator which loosely simulates a planet orbiting in a binary star
system.

Performance

planet simulates a planet orbiting in a binary star system. The outputs are
the x, y and z coordinates of the orbiting planet. It is possible for the
planet to achieve escape velocity by a close encounter with a star. This
makes this system somewhat unstable.

kmass1 is the mass of the first star,

kmass2 is the mass of the second star,

ksep determines the distance between the two stars,

ix, iy, iz are the initial x, y and z coordinates of the planet,

ivx, ivy, ivz are the initial velocity vector components for the planet.

idelta is the step size used to approximate the differential equation.

ifriction is a value for friction which can used to keep the system from
blowing up.

Example

           instr 1

idur       =     p3
iamp       =     p4
km1        =     p5
km2        =     p6
ksep       =     p7
ix         =     p8
iy         =     p9
iz         =     p10
ivx        =     p11
ivy        =     p12
ivz        =     p13
ih         =     p14
ifric      =     p15

kamp   linseg     0, .002, iamp, idur-.004, iamp, .002, 0

ax, ay, az planet km1, km2, ksep, ix, iy, iz, ivx, ivy, ivz, ih, ifric

           outs   ax*kamp, ay*kamp

           endin
;   Sta  Dur  Amp   M1  M2  Sep  X   Y  Z  VX  VY  VZ   h   Frict
i1  0    1    5000  .5  .35 2.2  0  .1  0  .5  .6  -.1  .5  -0.1
i1  +    .    .     .5  0   0    0  .1  0  .5  .6  -.1  .5   0.1
i1  .    .    .     .4  .3  2    0  .1  0  .5  .6  -.1  .5   0.0
i1  .    .    .     .3  .3  2    0  .1  0  .5  .6  -.1  .5   0.1
i1  .    .    .     .25 .3  2    0  .1  0  .5  .6  -.1  .5   1.0
i1  .    .    .     .2  .5  2    0  .1  0  .5  .6  -.1  .1   1.0

Author

Hans Mikelson
December 1998

------------------------------------------------------------------------
Banks of sliders

slider8,slider16,slider32,slider64
slider8f, slider16f,slider32f,slider64f
islider8,islider16,islider32,islider64
s16b14,is16b14,s32b14,is32b14

SYNTAX

k1,k2,k3,k4,k5,k6,k7,k8 slider8 ichan, ictlnum1, imin1, imax1, init1, ifn1, ...,\
                                       ictlnum8, imin8, imax8, init8, ifn8    

k1, ... , k16   slider16  ichan, ictlnum1,  imin1,  imax1,  init1,  ifn1, ...., \
                                 ictlnum16, imin16, imax16, init16, ifn16

k1, ... , k32   slider32  ichan, ictlnum1,  imin1,  imax1,  init1,  ifn1, ...., \
                                 ictlnum32, imin32, imax32, init32, ifn32

k1, ... , k64   slider64  ichan, ictlnum1,  imin1,  imax1,  init1,  ifn1, ...., \
                                 ictlnum64, imin64, imax64, init64, ifn64

k1,k2,k3,k4,k5,k6,k7,k8	slider8f ichan, ictlnum1, imin1, imax1, init1, ifn1, icutoff1, ...., \
                                        ictlnum8, imin8, imax8, init8, ifn8, icutoff8
   
k1, ... , k16   slider16f ichan, ictlnum1,  imin1,  imax1,  init1,  ifn1,  icutoff1, .... , \
                                 ictlnum16, imin16, imax16, init16, ifn16, icutoff16

k1, ... , k32   slider32f ichan, ictlnum1,  imin1,  imax1,  init1,  ifn1,  icutoff1, .... , \
                                 ictlnum32, imin32, imax32, init32, ifn32, icutoff32

k1, ... , k64   slider64f ichan, ictlnum1,  imin1,  imax1,  init1,  ifn1,  icutoff1, .... , \
                                 ictlnum64, imin64, imax64, init64, ifn64, icutoff64

i1, ... , i8 islider8            ichan, ictlnum1, imin1, imax1, ifn1, ...., \
                                        ictlnum8, imin8, imax8, ifn8


i1, ... , i16 islider16          ichan, ictlnum1,  imin1,  imax1,  ifn1, ...., \
                                        ictlnum16, imin16, imax16, ifn16

i1, ... , i32 islider32          ichan, ictlnum1,  imin1,  imax1,  ifn1, ...., \
                                        ictlnum32, imin32, imax32, ifn32

i1, ... , i64 islider64        ichan, ictlnum1,  imin1,  imax1,  ifn1, ...., \
                                      ictlnum64, imin64, imax64, ifn64

i1, ... , i16   s16b14 	       ichan, ictlno_msb1, ictlno_lsb1, imin1, imax1, initvalue1, ifn1, ....., \
                      		      ictlno_msb16, ictlno_lsb16, imin16, imax16, initvalue16, ifn16

i1, ... , i16   is16b14        ichan, ictlno_msb1, ictlno_lsb1, imin1, imax1, ifn1, .......... \
				      ictlno_msb16, ictlno_lsb16, imin16, imax16, ifn16

i1, ... , i32   s32b14 	       ichan, ictlno_msb1, ictlno_lsb1, imin1, imax1, initvalue1, ifn1, ....., \
                      		      ictlno_msb32, ictlno_lsb32, imin32, imax32, initvalue32, ifn32

i1, ... , i32   is32b14        ichan,  ictlno_msb1, ictlno_lsb1, imin1, imax1, ifn1, .......... \
				       ictlno_msb32, ictlno_lsb32, imin32, imax32, ifn32


DESCRIPTION

MIDI slider control banks 


INITIALIZATION
i1 ... i64 - output values

ichan - midi channel (1-16)

ictlnum1 ... ictlnum64 - midi control number
ictlno_msb1 .... ictlno_msb32 - midi control number (most significant byte)
ictlno_lsb1 .... ictlno_lsb32 - midi control number (less significant byte)
imin1 ... imin64 - minimum values for each controller
imax1 ... imax64 - maximum values for each controller
init1 ... init64 - inital value for each controller
ifn1 ... ifn64 - function table for conversion for each controller
icutoff1 ... icutoff64 - low pass filter frequency cutoff for each controller

PERFORMANCE

k1 ... k64 - output values

isliderN,  sliderN and sliderNf are banks of MIDI controller 
(useful when using midi mixer such as KAWAI MM-16 or others for
changing whatever sound  parameter in realtime. A software slider bank
will be avalaible within short time). 
The raw midi control messages at the input port are converted to agree
with iminN and imaxN,  and an initial value can be set. Also an
optional non-interpolated function table with a custom translation
curve is allowed, useful for enabling exponential response curves. 

When no function table translation is required, set the ifnN value to
0, else set ifnN to a valid function table number.  When table
translation is enabled (i.e. setting ifnN value to a non-zero number
referring to an already allocated function table), initN value should
be set equal to iminN or imaxN value, else the initial output value
will not be the same as specified in initN argument.

slider8 allows a bank of 8 different midi control message numbers,
slider16 does the same with a bank of 16 controls, and so on.  

sliderNf filter the signal before output for eliminating
discontinuities due to the low resolution of the MIDI (7 bit); the
cutoff frequency can be set separately for each controller (suggested
range: .1 to 5 cps). Warning! sliderNf opcodes do not output the
required initial value immediately, but only after some k-cycle
because the filter slightly delays the output.

As the input and output arguments are many, you can split the line
using '\' (backslash) character (new in 3.47 version) to improve the
readability. Using these opcodes is quite more efficient than using
the separate ones (ctrl7 and ktone) when more controllers are
required. 

In isliderN there is not an initial-value input argument because the
output is get directly from current status of internal controller
array of Csound. 

isNb14 and sNb14 opcodes are the 14-bit versions of these banks of
controllers. 

------------------------------------------------------------------------
ar      pareq   asig, kc, iv, iq, imode

iv is volume boost or cut
iq is the quality factor (sqrt(.5) is no resonance)
imode is 0=Peaking EQ, 1=Low Shelf, 2=High Shelf

Performance

kc is the centre of shelf value
asig is the incoming signal

Eqample:

        instr 15
ifc     =     p4             ; Center / Shelf
iq      =     p5             ; Quality factor sqrt(.5) is no resonance
iv      =     ampdb(p6)      ; Volume Boost/Cut
imode   =     p7             ; Mode 0=Peaking EQ, 1=Low Shelf, 2=High Shelf
kfc     linseg  ifc*2, p3, ifc/2
asig    rand  5000                     ; Random number source for testing
aout    pareq asig, kfc, iv, iq, imode ; Parmetric equalization
        outs  aout, aout               ; Output the results
endin

; SCORE:
;   Sta  Dur  Fcenter  Q        Boost/Cut(dB)  Mode
i15 0    1    10000   .2          12             1
i15 +    .    5000    .2          12             1
i15 .    .    1000    .707       -12             2
i15 .    .    5000    .1         -12             0

Hans Mikelson
------------------------------------------------------------------------
oscil3, foscil3, loscil3, vdelay3, table3, itable3, deltap3

These are experimental opcodes which use cubic interpolation rather
than teh linear interpolation of oscili, foscili, loscili, vdelay,
tablei, itablei and  deltapi.  Testing so far has shown that oscil3
works and gives a better sound (on a 32 point sine wave).  The others
have not been tested and so shoudl be used with some care.  Feedback
on these is most acceptable
JPff

------------------------------------------------------------------------