Server Plugin API:

Filter: These four constants identify the calculation rates of inputs in SuperCollider.

`calc_ScalarRate`

- Initial rate. Conventionally known in the language as ".ir".
`calc_BufRate`

- Control rate. Conventionally known in the language as ".kr".
`calc_FullRate`

- Audio rate. Conventionally known in the language as ".ar".
`calc_DemandRate`

- Demand rate.

These helper macros assume that there is a ugen object called `unit`

in the local scope.

`IN(index)`

- A single block of audio-rate input as a float* at the given index. Index 0 is the first input to the ugen, index 1 the second input, and so forth.
`IN0(index)`

- A single sample of control-rate input as a float, at the given index.
`OUT(index)`

- A single block of audio-rate output as a float* at the given index.
`OUT0(index)`

- A single sample of control-rate input as a float, at the given index.
`INRATE(index)`

- Get the rate of a given input index. This will be one of the four rates.
`INBUFLENGTH(index)`

- Get the block size of a given input index.
`SAMPLERATE`

- Sample rate of the server in Hertz.
`SAMPLEDUR`

- Sample period of the server in seconds.
`BUFLENGTH`

- Length in samples of an audio buffer (that is, the number of samples in a control period).
`BUFRATE`

- Control rate of the server in Hertz.
`BUFDUR`

- Control period of the server in seconds.
`FULLRATE`

`FULLBUFLENGTH`

`GET_BUF`

- The recommended way to retrieve a buffer. Take the first input of this UGen and use it as a buffer number. This dumps a number of variables into the local scope:
`buf`

- a pointer to the`SndBuf`

instance`bufData`

- the raw float data from the buffer`bufChannels`

- the number of channels in the buffer`bufSamples`

- the number of samples in the buffer`bufFrames`

- the number of frames in the buffer

The buffer is locked using the

`LOCK_SNDBUF`

macro. Buffer lock operations are specific to supernova, and don't do anything in vanilla scsynth. `GET_BUF_SHARED`

- Like
`GET_BUF`

, but the buffer is locked using`LOCK_SNDBUF_SHARED`

. `SIMPLE_GET_BUF`

- Like
`GET_BUF`

, but only creates the`buf`

variable and does not lock the buffer. `SIMPLE_GET_BUF_EXCLUSIVE`

- Like
`SIMPLE_GET_BUF`

, but locks the buffer with`LOCK_SNDBUF`

. `SIMPLE_GET_BUF_SHARED`

- Like
`SIMPLE_GET_BUF`

, but locks the buffer with`LOCK_SNDBUF_SHARED`

.

The following macros are for use in supernova. They still exist in scsynth, but will have no effect.

RGen is a pseudorandom number generator API. Most ugen developers are not interested in seeding their own RGens and would prefer to draw from a global RGen instance supplied by SuperCollider. This can be retrieved with the code:

`uint32 RGen::trand()`

- Return a uniformly distributed random 32-bit integer.
`double RGen::drand()`

- Return a uniformly distributed random double in [0,1).
`float RGen::frand()`

- Random float in [0,1).
`float RGen::frand0()`

- Random float in [1,2).
`float RGen::frand2()`

- Random float in [-1,1).
`float RGen::frand8()`

- Random float in [-0.125,0.125).
`float RGen::fcoin()`

- Either -1 or +1.
`float RGen::flinrand()`

- Linearly distributed random float in [0,1), with a bias towards the 0 end.
`float RGen::fbilinrand()`

- Bilinearly distributed random float in (-1,1), with a bias towards 0.
`float RGen::fsum3rand()`

- A crude but fast approximation to a Gaussian distribution. Results are always in the range (-1,1). The variance is 1/6 and the standard deviation is 0.41.
^{1} `int32 RGen::irand(int32 scale)`

- Random int in [0,scale).
`int32 RGen::irand2(int32 scale)`

- Random int in [-scale,+scale].
`int32 RGen::ilinrand(int32 scale)`

- Linearly distributed random int in [0,scale), with a bias towards the 0 end.
`int32 RGen::ibilinrand(int32 scale)`

- Bilinearly distributed random int in (-scale,scale), with a bias towards the 0.
`double RGen::linrand()`

- Linearly distributed random double in [0,1), with a bias towards the 0 end.
`double RGen::bilinrand()`

- Bilinearly distributed random double in (-1,1), with a bias towards 0.
`double RGen::exprandrng(double lo, double hi)`

- Exponentially distributed random double in [lo,hi).
`double RGen::exprand(double scale)`

`double RGen::biexprand(double scale)`

`double RGen::exprand(double scale)`

`double RGen::sum3rand(double scale)`

- Double version of
`RGen::fsum3rand`

.

`bool sc_isnan(float/double x)`

- Checks whether
`x`

is NaN. This is a legacy function, use`std::isnan`

instead. `bool sc_isfinite(float/double x)`

- Checks whether
`x`

is finite. This is a legacy function, use`std::isfinite`

instead. `int32 sc_grayCode(int32 x)`

- Convert binary to Gray code.

The following unary functions are available for both float32 and float64, and are the same as in sclang (minus the "sc_" prefixes):

`sc_midicps`

`sc_cpsmidi`

`sc_midiratio`

`sc_ratiomidi`

`sc_octcps`

`sc_cpsoct`

`sc_ampdb`

`sc_dbamp`

`sc_cubed`

`sc_sqrt`

`sc_hanwindow`

`sc_welwindow`

`sc_triwindow`

`sc_rectwindow`

`sc_scurve`

`sc_ramp`

`sc_sign`

`sc_distort`

`sc_softclip`

`sc_ceil`

`sc_floor`

`sc_reciprocal`

`sc_frac`

`sc_log2`

(legacy -- use`std::log2(std::abs(x))`

)`sc_log10`

(legacy -- use`std::log10(std::abs(x))`

)`sc_trunc`

(legacy -- use`std::trunc`

)

The following unary functions are available for both float32 and float64, but have no sclang equivalent:

`zapgremlins(x)`

- Replaces NaNs, infinities, very large and very small numbers (including denormals) with zero. This is useful in ugen feedback to safeguard from pathological behavior. (Note lack of sc_ prefix.)
`sc_bitriwindow(x)`

- Alternative to
`sc_triwindow`

using absolute value. `sc_scurve0(x)`

- Same as
`sc_scurve`

, but assumes that`x`

is in the interval [0, 1]. `sc_distortneg(x)`

- A one-sided distortion function. Same as
`distort`

for`x > 0`

, and the identity function for`x <= 0`

. `taylorsin(x)`

- Taylor series approximation of
`sin(x)`

out to`x**9 / 9!`

. (Note lack of sc_ prefix.) `sc_lg3interp(x1, a, b, c, d)`

- Cubic Lagrange interpolator.
`sc_CalcFeedback(delaytime, decaytime)`

- Determines the feedback coefficient for a feedback comb filter with the given delay and decay times.
`sc_wrap1(x)`

- Wrap
`x`

around ±1, wrapping only once. `sc_fold1(x)`

- Fold
`x`

around ±1, folding only once.

`sc_wrap(in, lo, hi [, range])`

`sc_fold(in, lo, hi [, range [, range2]])`

`sc_pow(a, b)`

- Compute
`pow(a, b)`

, retaining the sign of`a`

. `sc_powi(x, unsigned int n)`

- Compute
`x^n`

, not necessarily retaining the sign of`x`

. `sc_hypotx(x, y)`

- Compute
`abs(x) + abs(y) - (min(abs(x), abs(y)) * (sqrt(2) - 1))`

, the minimum distance one will have to travel from the origin to (x,y) using only orthogonal and diagonal movements.

The following functions are the same as in sclang (minus the "sc_" prefixes):

`sc_mod(in, hi)`

(floats, doubles, ints)`sc_round(x, quant)`

(floats, doubles, ints)`sc_roundUp(x, quant)`

(floats, doubles, ints)`sc_trunc(x, quant)`

(floats, doubles, ints)`sc_gcd(a, b)`

(ints, longs, floats)`sc_lcm(a, b)`

(ints, longs, floats)`sc_bitAnd(a, b)`

(ints)`sc_bitOr(a, b)`

(ints)`sc_leftShift(a, b)`

(ints)`sc_rightShift(a, b)`

(ints)`sc_unsignedRightShift(a, b)`

(ints)`sc_thresh(a, b)`

`sc_clip2(a, b)`

`sc_wrap2(a, b)`

`sc_fold2(a, b)`

`sc_excess(a, b)`

`sc_scaleneg(a, b)`

`sc_amclip(a, b)`

`sc_ring1(a, b)`

`sc_ring2(a, b)`

`sc_ring3(a, b)`

`sc_ring4(a, b)`

`sc_difsqr(a, b)`

`sc_sumsqr(a, b)`

`sc_sqrsum(a, b)`

`sc_sqrdif(a, b)`

`sc_atan2(a, b)`

(legacy -- use`std::atan2`

)

The following constants are doubles:

`pi`

`pi2`

= pi/2`pi32`

= 3pi/2`twopi`

= 2pi`rtwopi`

(1/2pi)`log001`

= log(0.001)`log01`

= log(0.01)`log1`

= log(0.1)`rlog2`

= 1/log(2)`sqrt2`

= sqrt(2)`rsqrt2`

= 1/sqrt(2)`truncDouble`

= 3 * 2^51 (used to truncate precision)

The following constants are floats:

`pi_f`

`pi2_f`

`pi32_f`

`twopi_f`

`sqrt2_f`

`rsqrt2_f`

`truncFloat`

= 3 * 2^22 (used to truncate precision)

The macros in this section are legacy features. They are seen in many of SuperCollider's built-in ugens, and are intended to provide more efficient alternatives to the standard `for (int i = 0; i < inNumSamples; i++) { out[i] = in[i] }`

loop. These efficiency savings are negligible on modern systems and use of these macros is not recommended, especially since they make debugging difficult.

`LOOP(length, stmt)`

- Execute code
`stmt`

,`length`

times. `LOOP1(length, stmt)`

- A faster drop-in alternative to
`LOOP`

, which assumes that`length > 0`

so a branch instruction is saved. `LooP(length) stmt`

- An alternative to LOOP/LOOP1 that is more debugger-friendly. The body of the loop comes after the call to
`LooP`

. `ZIN(index)`

- Similar to
`IN`

, but subtracts 1 from the pointer to correct for off-by-one errors when using`LOOP`

and`ZXP`

. `ZOUT(index)`

- Same as
`OUT`

, but subtracts 1 from the pointer to correct for off-by-one errors when using`LOOP`

and`ZXP`

. `ZIN0(index)`

- Alias for
`IN0`

. `ZOUT0(index)`

- Alias for
`OUT0`

. `ZXP(z)`

- Pre-increment and dereference
`z`

. `ZX(z)`

- Dereference
`z`

. `PZ(z)`

- Pre-increment
`z`

. `ZP(z)`

- Does nothing.
`ZOFF`

- Return 1.

helpfile source: /usr/local/share/SuperCollider/HelpSource/Reference/ServerPluginAPI.schelp

link::Reference/ServerPluginAPI::

link::Reference/ServerPluginAPI::