
================================ MANUALS ===============================

ar      rbjeq   asig, kfco, klvl, kQ, kS[, imode]

DESCRIPTION
-----------

Parametric equalizer and filter opcode with 7 filter types, based on
algorithm by Robert Bristow-Johnson.

INITIALIZATION
--------------

imode (optional, defaults to zero) - sum of:

    1: skip initialization (should be used in tied, or re-initialized
       notes only).

  and exactly one of the following values to select filter type:

    0: resonant lowpass filter. kQ controls the resonance: at the
       cutoff frequency (kfco), the amplitude gain is kQ (e.g. 20 dB
       for kQ = 10), and higher kQ values result in a narrower
       resonance peak. If kQ is set to sqrt(0.5) (about 0.7071),
       there is no resonance, and the filter has a response that is
       very similar to that of butterlp. If kQ is less than sqrt(0.5),
       there is no resonance, and the filter has a -6 dB / octave
       response from about kfco * kQ to kfco. Above kfco, there is
       always a -12 dB / octave cutoff.

       NOTE: the rbjeq lowpass filter is basically the same as
         ar     pareq   asig, kfco, 0, kQ, 2
       but is faster to calculate.

    2: resonant highpass filter. The parameters are the same as for
       the lowpass filter, but the equivalent filter is butterhp if
       kQ is 0.7071, and "ar pareq asig, kfco, 0, kQ, 1" in other
       cases.

    4: bandpass filter. kQ controls the bandwidth, which is kfco / kQ,
       and must be always less than sr / 2. The bandwidth is measured
       between -3 dB points (i.e. amplitude gain = 0.7071), beyond
       which there is a +/- 6 dB / octave slope.
       This filter type is very similar to
         ar     butterbp asig, kfco, kfco / kQ

    6: band-reject filter, with the same parameters as the bandpass
       filter, and a response similar to that of butterbr.

    8: peaking EQ. It has an amplitude gain of 1 (0 dB) at 0 Hz and
       sr / 2, and klvl at the center frequency (kfco). Thus, klvl
       controls the amount of boost (if it is greater than 1), or
       cut (if it is less than 1). Setting klvl to 1 results in a
       flat response. Similarly to the bandpass and band-reject
       filters, the bandwidth is determined by kfco / kQ (which must
       be less than sr / 2 again); however, this time it is between
       sqrt(klvl) points (or, in other words, half the boost or cut
       in decibels).
       NOTE: excessively low or high values of klvl should be avoided
       (especially with 32-bit floats), though the opcode was tested
       with klvl = 0.01 and klvl = 100. klvl = 0 is always an error,
       unlike in the case of pareq, which does allow a zero level.

   10: low shelf EQ, controlled by klvl and kS (kQ is ignored by this
       filter type). There is an amplitude gain of klvl at zero
       frequency, while the level of high frequencies (around sr / 2)
       is not changed. At the corner frequency (kfco), the gain is
       sqrt(klvl) (half the boost or cut in decibels). The kS
       parameter controls the steepness of the slope of the frequency
       response (see below).

   12: high shelf EQ. Very similar to the low shelf EQ, but affects
       the high frequency range.

  the default value for imode is zero (lowpass filter, initialization
  not skipped).

PERFORMANCE
-----------

ar - the output signal.

asig - the input signal.
  NOTE: if the input contains silent sections, on Intel CPUs a
  significant slowdown can occur due to denormals. In such cases, it
  is recommended to process the input signal with "denorm" opcode
  before filtering it with rbjeq (and actually many other filters).

kfco - cutoff, corner, or center frequency, depending on filter type,
  in Hz. It must be greater than zero, and less than sr / 2 (the range
  of about sr * 0.0002 to sr * 0.49 should be safe).

klvl - level (amount of boost or cut), as amplitude gain (e.g. 1: flat
  response, 4: 12 dB boost, 0.1: 20 dB cut); zero or negative values
  are not allowed. It is recognized by the peaking and shelving EQ
  types (8, 10, 12) only, and is ignored by other filters.

kQ - resonance (also kfco / bandwidth in many filter types). Not used
  by the shelving EQs (imode = 10 and 12). The exact meaning of this
  parameter depends on the filter type (see above), but it should be
  always greater than zero, and usually (kfco / kQ) less than sr / 2.

kS - shelf slope parameter for shelving filters. Must be greater than
  zero; a higher value means a steeper slope, with resonance if
  kS > 1 (however, a too high kS value may make the filter unstable).
  If kS is set to exactly 1, the shelf slope is as steep as possible
  without a resonance. Note that the effect of kS - especially if it
  is greater than 1 - also depends on klvl, and it does not have any
  well defined unit.

EXAMPLE
-------

; ---- orchestra ----

sr      =  44100
ksmps   =  10
nchnls  =  1

        instr 1

a1      vco2    10000, 155.6            ; sawtooth wave
kfco    expon   8000, p3, 200           ; filter frequency
a1      rbjeq   a1, kfco, 1, kfco * 0.005, 1, 0 ; resonant lowpass
        out a1

        endin

; ---- score ----

i 1 0 5
e

AUTHORS
-------

Original algorithm by Robert Bristow-Johnson
Csound orchestra version by Josep M Comajuncosas, Aug 1999
Converted to C (with optimizations and bug fixes) by Istvan Varga,
Dec 2002

========================================================================

kr      delayk  ksig, idel[, imode]
kr      vdel_k  ksig, kdel, imdel[, imode]

DESCRIPTION
-----------

k-rate delay opcodes.

INITIALIZATION
--------------

idel - delay time (in seconds) for delayk. It is rounded to the
  nearest integer multiple of a k-cycle (i.e. 1/kr).

imode - sum of:
  1: skip initialization (e.g. in tied notes)
  2: hold the first input value during the initial delay, instead of
     outputting zero. This is mainly of use when delaying envelopes
     that do not start at zero.

        ^__          imode = 0   ^   ___
        |  \                     |   |  \
        |   \            =>      |   |   \
        |    \                   |   |    \
       -+------------>          -+------------>
        |                        |

        ^__          imode = 2   ^______
        |  \                     |      \
        |   \            =>      |       \
        |    \                   |        \
       -+------------>          -+------------>
        |                        |

imdel - maximum delay time for vdel_k, in seconds.

PERFORMANCE
-----------

kr - the output signal. Note: none of the opcodes interpolate the
  output.

ksig - the input signal.

kdel - delay time (in seconds) for vdel_k. It is rounded to the
  nearest integer multiple of a k-cycle (i.e. 1/kr).

AUTHOR
------

Istvan Varga
Dec 2002

========================================================================

NOTE: all the following opcodes are by Gabriel Maldonado
     _________________________________________________________________

   tab, tabw

   ir tab indx, ifn[, ixmode]
   kr tab kndx, ifn[, ixmode]
   ar tab xndx, ifn[, ixmode]

   tabw isig, indx, ifn [,ixmode]
   tabw ksig, kndx, ifn [,ixmode]
   tabw asig, andx, ifn [,ixmode]

   DESCRIPTION

   Fast table opcodes. Faster than table and tablew because don't allow
   wrap-around and limit and don't check index validity. Have been
   implemented in order to provide fast access to arrays. Support
   non-power of two tables (can be generated by any GEN function by
   giving a negative length value).

   INITIALIZATION

   ifn - table number

   ixmode (optional; default = 0) -  ==0 - xndx and ixoff ranges match
   the length of the table.
                                                            !=0 - xndx
   and ixoff have a 0 to 1 range.
   isig - input value to write

   indx - table index

   PERFORMANCE

   asig, ksig  - input signal to write
   andx, kndx - table index
   tab and tabw opcodes are similar to table and tablew, but are faster
   and support tables having non-power-of-two length.

   Special care of index value must be taken into account. Index values
   out of the table allocated space will crash Csound.
     _________________________________________________________________

  Trigger Metronome

   ktrig metro kfreq [, initphase]

   DESCRIPTION

   Generate a metronomic signal to be used in any circumstance an
   isochronous trigger is needed.

   INITIALIZATION

   initphase - initial phase value (in the 0 to 1 range)

   PERFORMANCE

   ktrig - output trigger signal
   kfreq - frequency of trigger bangs in cps

   metro is a simple opcode that outputs a sequence of isochronous bangs
   (that is 1 values) each 1/kfreq seconds. Trigger signals can be used
   in any circumstance, mainly to temporize realtime algorithmic
   compositional structures.
     _________________________________________________________________

  Mandelbrot Set

   kiter, koutrig mandel ktrig, kx, ky, kmaxIter

   DESCRIPTION

   Returns the number of iterations corresponding to a given point of
   complex plane by applying the Mandelbrot set formula.

   PERFORMANCE

   kiter- number of iterations
   koutrig - output trigger signal
   ktrig - input trigger signal
   kx, ky - coordinates of a given point belonging to the complex plane
   kmaxIter - maximum iterations allowed

   mandel is an opocode that allows to use the Mandelbrot set formula to
   generate an output that can be applied to any musical (or non-musical)
   parameter. It has two output arguements, kiter, that contains the
   iteration number of a given point, and koutrig, that generates a
   trigger bang each time kiter changes. A new number of iterations is
   evaluated only when ktrig is set to a non-zero value. User have to set
   the coordinates of the complex plane inside kx and ky arguments, while
   kmaxIter contains the maximum number of iteration the user intend to
   use. Output values, that are integer numbers, can be mapped in any
   sorts of ways by the composer.
     _________________________________________________________________

  K-rate Variable Time Delay

   kr, vdelayk ksig, kdel, imaxdel [, iskip, imode]

   DESCRIPTION

   Variable delay applied to a k-rate signal

   INITIALIZATION

   imaxdel - maximum value of delay in seconds.
   iskip (optional) - Skip initialization if present and non zero.
   imode (optional) - if non-zero it suppresses linear interpolation.
   While, normally, interpolation increases the quality of a signal, it
   should be suppressed if using vdelay with discrete control signals,
   such as, for example, trigger signals.

   PERFORMANCE

   kr - delayed output signal
   ksig - input signal
   kdel - delay time in seconds can be varied at k-rate

   vdelayk is similar to vdelay, but works at k-rate. It is designed to
   delay control signals, to be used, for example, in algorithmic
   composition.
     _________________________________________________________________

  Cellular Automata

   vcella ktrig, kreinit, ioutFunc, initStateFunc, iRuleFunc, ielements,
   irulelen [, iradius]

   DESCRIPTION

   Unidimensional Cellular Automata applied to Csound vectors

   INITIALIZATION

   ioutFunc - number of the table where the state of each cell is stored
   initStateFunc - number of a table containig the inital states of each
   cell
   iRuleFunc - number of a lookup table containing the rules
   ielements - total number of cells
   irulelen - total number of rules
   iradius (optional) - radius of Cellular Automata. At present time CA
   radius can be 1 or 2 (1 is the default)

   PERFORMANCE

   ktrig - trigger signal. Each time it is non-zero, a new generation of
   cells is evaluated
   kreinit - trigger signal. Each time it is non-zero, state of all cells
   is forced to be that of initStateFunc.

   vcella supports unidimensional cellular automata, where the state of
   each cell is stored in ioutFunc. So ioutFunc is a vector containing
   current state of each cell. This variant vector can be used together
   with any other vector-based opcode, such as adsynt, vmap, vpowv etc.

   initStateFunc is an input vector containing the inital value of the
   row of cells, while iRuleFunc is an input vector containing the rules
   in the form of a lookup table. Notice that initStateFunc and iRuleFunc
   can be updated during the performance by means of other vector-based
   opcodes (for example vcopy) in order to force to change rules and
   status at performance time.

   A new generation of cells is evaluated each time ktrig contains a
   non-zero value. Also the status of all cells can be forced to assume
   the status corresponding to the contents of initStateFunc each time
   kreinit contains a non-zero value.

   Radius of CA algorithm can be 1 or 2 (optional iradius arguement).
     _________________________________________________________________

  ZAK space read access inside expressions

   iout = zr(iIndex)
   kout = zr(kIndex)
   aout = zr(aIndex)

   DESCRIPTION

   Allow to read ZAK space inside expressions.

   These opcodes are identical to zir, zkr and zar, but can be used in
   function fashion.
     _________________________________________________________________

  Table Read Access inside expressions

   tb0_init ifn
   tb1_init ifn
   ....
   tb15_init ifn

   iout = tb0(iIndex)
   kout = tb0(kIndex)
   iout = tb1(iIndex)
   kout = tb1(kIndex)
   ....
   iout = tb15(iIndex)
   kout = tb15(kIndex)

   DESCRIPTION

   Allow to read tables in function fashion, to be used inside
   expressions

   At present time Csound only supports functions with a single input
   argument. However, to access table elements, user must provide two
   numbers, i.e. the number of table and the index of element. So, in
   order to allow to access a table element with a function, a previous
   preparation step should be done.

   There are 16 different opcodes whose name is associated with a number
   from 0 to 15. User can associate a specific table with each opcode (so
   the maximum number of tables that can be accessed in function fashion
   is 16). Prior to access a table, user must associate the table with
   one of the 16 opcodes by means of an opcode chosen among
   tb0_init...tb15_init. For example,

   tb0_init  1

   associates table 1 with tb0( ) function, so that, each element of
   table 1 can be accessed (in function fashion)  with:

   kvar = tb0(k_some_index_of_table1) * k_some_other_var
          ivar  = tb0(i_some_index_of_table1) + i_some_other_var
          etc...

   By using these opcodes, user can drastically reduce the number of
   lines of an orchestra, improving its readability.
     _________________________________________________________________

   ktrig changed kvar1 [, kvar2,..., kvarN]

   changed opcode outputs a trigger signal that informs when one (or
   several ones) of its k-rate arguments has changed. Useful with
   valuator widgets or MIDI controllers.

