zzkt/rsc3
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
rsc3/doc-schelp/HelpSource/Reference/ServerPluginAPI.scrbl

836 lines
14 KiB
Text
Raw Permalink Normal View History

docs (scm, schelp, scrbl & html)
2022-08-24 13:53:18 +00:00
#lang scribble/manual
@(require (for-label racket))
@title{Server Plugin API}
Reference for writing unit generators@section{categories}
Internals
@section{related}
Guides/WritingUGens
@section{section}
Input rates
These four constants identify the calculation rates of inputs in SuperCollider.
@section{definitionlist}
##
@racketblock[calc_ScalarRate::
|| Initial rate. Conventionally known in the language as ".ir".
## ]
@racketblock[calc_BufRate::
|| Control rate. Conventionally known in the language as ".kr".
## ]
@racketblock[calc_FullRate::
|| Audio rate. Conventionally known in the language as ".ar".
## ]
@racketblock[calc_DemandRate::
|| Demand rate.
::
]
@section{section}
UGen basics
These helper macros assume that there is a ugen object called
@racketblock[unit:: in the local scope.
]
@section{definitionlist}
##
@racketblock[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.
## ]
@racketblock[IN0(index)::
|| A single sample of control-rate input as a float, at the given index.
## ]
@racketblock[OUT(index)::
|| A single block of audio-rate output as a float* at the given index.
## ]
@racketblock[OUT0(index)::
|| A single sample of control-rate input as a float, at the given index.
## ]
@racketblock[INRATE(index)::
|| Get the rate of a given input index. This will be one of the four rates.
## ]
@racketblock[INBUFLENGTH(index)::
|| Get the block size of a given input index.
## ]
@racketblock[SAMPLERATE::
|| Sample rate of the server in Hertz.
## ]
@racketblock[SAMPLEDUR::
|| Sample period of the server in seconds.
## ]
@racketblock[BUFLENGTH::
|| Length in samples of an audio buffer (that is, the number of samples in a control period).
## ]
@racketblock[BUFRATE::
|| Control rate of the server in Hertz.
## ]
@racketblock[BUFDUR::
|| Control period of the server in seconds.
## ]
@racketblock[FULLRATE::
||
## ]
@racketblock[FULLBUFLENGTH::
||
::
]
@section{section}
Buffers
@section{definitionlist}
##
@racketblock[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:
]
@section{list}
##
@racketblock[buf:: - a pointer to the ]
@racketblock[SndBuf:: instance
## ]
@racketblock[bufData:: - the raw float data from the buffer
## ]
@racketblock[bufChannels:: - the number of channels in the buffer
## ]
@racketblock[bufSamples:: - the number of samples in the buffer
## ]
@racketblock[bufFrames:: - the number of frames in the buffer
::
The buffer is locked using the ]
@racketblock[LOCK_SNDBUF:: macro. Buffer lock operations are specific to supernova, and don't
do anything in vanilla scsynth.
## ]
@racketblock[GET_BUF_SHARED::
|| Like ]
@racketblock[GET_BUF::, but the buffer is locked using ]
@racketblock[LOCK_SNDBUF_SHARED::.
## ]
@racketblock[SIMPLE_GET_BUF::
|| Like ]
@racketblock[GET_BUF::, but only creates the ]
@racketblock[buf:: variable and does not lock the buffer.
## ]
@racketblock[SIMPLE_GET_BUF_EXCLUSIVE::
|| Like ]
@racketblock[SIMPLE_GET_BUF::, but locks the buffer with ]
@racketblock[LOCK_SNDBUF::.
## ]
@racketblock[SIMPLE_GET_BUF_SHARED::
|| Like ]
@racketblock[SIMPLE_GET_BUF::, but locks the buffer with ]
@racketblock[LOCK_SNDBUF_SHARED::.
::
The following macros are for use in supernova. They still exist in scsynth, but will have no effect.
]
@racketblock[
ACQUIRE_BUS_AUDIO(index)
ACQUIRE_BUS_AUDIO_SHARED(index)
RELEASE_BUS_AUDIO(index)
RELEASE_BUS_AUDIO_SHARED(index)
LOCK_SNDBUF(buf)
LOCK_SNDBUF_SHARED(buf)
LOCK_SNDBUF2(buf1, buf2)
LOCK_SNDBUF2_SHARED(buf1, buf2)
LOCK_SNDBUF2_EXCLUSIVE_SHARED(buf1, buf2)
LOCK_SNDBUF2_SHARED_EXCLUSIVE(buf1, buf2)
ACQUIRE_SNDBUF(buf)
ACQUIRE_SNDBUF_SHARED(buf)
RELEASE_SNDBUF(buf)
RELEASE_SNDBUF_SHARED(buf)
ACQUIRE_BUS_CONTROL(index)
RELEASE_BUS_CONTROL(index)
::
]
@section{section}
RGen
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:
@racketblock[
RGen& rgen = *unit->mParent->mRGen;
::
]
@section{definitionlist}
##
@racketblock[uint32 RGen\::trand()::
|| Return a uniformly distributed random 32-bit integer.
## ]
@racketblock[double RGen\::drand()::
|| Return a uniformly distributed random double in [0,1).
## ]
@racketblock[float RGen\::frand()::
|| Random float in [0,1).
## ]
@racketblock[float RGen\::frand0()::
|| Random float in [1,2).
## ]
@racketblock[float RGen\::frand2()::
|| Random float in [-1,1).
## ]
@racketblock[float RGen\::frand8()::
|| Random float in [-0.125,0.125).
## ]
@racketblock[float RGen\::fcoin()::
|| Either -1 or +1.
## ]
@racketblock[float RGen\::flinrand()::
|| Linearly distributed random float in [0,1), with a bias towards the 0 end.
## ]
@racketblock[float RGen\::fbilinrand()::
|| Bilinearly distributed random float in (-1,1), with a bias towards 0.
## ]
@racketblock[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. ]
@section{footnote}
The formula is
@racketblock[(rand() + rand() + rand() - 1.5) * 2/3::,
technically a shifted and stretched order-3 Irwin-Hall distribution. ::
## ]
@racketblock[int32 RGen\::irand(int32 scale)::
|| Random int in [0,scale).
## ]
@racketblock[int32 RGen\::irand2(int32 scale)::
|| Random int in [-scale,+scale].
## ]
@racketblock[int32 RGen\::ilinrand(int32 scale)::
|| Linearly distributed random int in [0,scale), with a bias towards the 0 end.
## ]
@racketblock[int32 RGen\::ibilinrand(int32 scale)::
|| Bilinearly distributed random int in (-scale,scale), with a bias towards the 0.
## ]
@racketblock[double RGen\::linrand()::
|| Linearly distributed random double in [0,1), with a bias towards the 0 end.
## ]
@racketblock[double RGen\::bilinrand()::
|| Bilinearly distributed random double in (-1,1), with a bias towards 0.
## ]
@racketblock[double RGen\::exprandrng(double lo, double hi)::
|| Exponentially distributed random double in [lo,hi).
## ]
@racketblock[double RGen\::exprand(double scale)::
||
## ]
@racketblock[double RGen\::biexprand(double scale)::
||
## ]
@racketblock[double RGen\::exprand(double scale)::
||
## ]
@racketblock[double RGen\::sum3rand(double scale)::
|| Double version of ]
@racketblock[RGen\::fsum3rand::.
::
]
@section{section}
Unary operators
@section{definitionlist}
##
@racketblock[bool sc_isnan(float/double x)::
|| Checks whether ]
@racketblock[x:: is NaN. This is a legacy function, use ]
@racketblock[std\::isnan:: instead.
## ]
@racketblock[bool sc_isfinite(float/double x)::
|| Checks whether ]
@racketblock[x:: is finite. This is a legacy function, use ]
@racketblock[std\::isfinite:: instead.
## ]
@racketblock[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):
]
@section{list}
##
@racketblock[sc_midicps::
## ]
@racketblock[sc_cpsmidi::
## ]
@racketblock[sc_midiratio::
## ]
@racketblock[sc_ratiomidi::
## ]
@racketblock[sc_octcps::
## ]
@racketblock[sc_cpsoct::
## ]
@racketblock[sc_ampdb::
## ]
@racketblock[sc_dbamp::
## ]
@racketblock[sc_cubed::
## ]
@racketblock[sc_sqrt::
## ]
@racketblock[sc_hanwindow::
## ]
@racketblock[sc_welwindow::
## ]
@racketblock[sc_triwindow::
## ]
@racketblock[sc_rectwindow::
## ]
@racketblock[sc_scurve::
## ]
@racketblock[sc_ramp::
## ]
@racketblock[sc_sign::
## ]
@racketblock[sc_distort::
## ]
@racketblock[sc_softclip::
## ]
@racketblock[sc_ceil::
## ]
@racketblock[sc_floor::
## ]
@racketblock[sc_reciprocal::
## ]
@racketblock[sc_frac::
## ]
@racketblock[sc_log2:: (legacy -- use ]
@racketblock[std\::log2(std\::abs(x))::)
## ]
@racketblock[sc_log10:: (legacy -- use ]
@racketblock[std\::log10(std\::abs(x))::)
## ]
@racketblock[sc_trunc:: (legacy -- use ]
@racketblock[std\::trunc::)
::
The following unary functions are available for both float32 and float64, but have no sclang equivalent:
]
@section{definitionlist}
##
@racketblock[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.)
## ]
@racketblock[sc_bitriwindow(x)::
|| Alternative to ]
@racketblock[sc_triwindow:: using absolute value.
## ]
@racketblock[sc_scurve0(x)::
|| Same as ]
@racketblock[sc_scurve::, but assumes that ]
@racketblock[x:: is in the interval [0, 1].
## ]
@racketblock[sc_distortneg(x)::
|| A one-sided distortion function. Same as ]
@racketblock[distort:: for ]
@racketblock[x > 0::, and the identity function for ]
@racketblock[x <= 0::.
## ]
@racketblock[taylorsin(x)::
|| Taylor series approximation of ]
@racketblock[sin(x):: out to ]
@racketblock[x**9 / 9!::. (Note lack of sc_ prefix.)
## ]
@racketblock[sc_lg3interp(x1, a, b, c, d)::
|| Cubic Lagrange interpolator.
## ]
@racketblock[sc_CalcFeedback(delaytime, decaytime)::
|| Determines the feedback coefficient for a feedback comb filter with the given delay and decay times.
## ]
@racketblock[sc_wrap1(x)::
|| Wrap ]
@racketblock[x:: around ±1, wrapping only once.
## ]
@racketblock[sc_fold1(x)::
|| Fold ]
@racketblock[x:: around ±1, folding only once.
::
]
@section{section}
Binary operators
@section{definitionlist}
##
@racketblock[sc_wrap(in, lo, hi [, range])::
||
## ]
@racketblock[sc_fold(in, lo, hi [, range [, range2]])::
||
## ]
@racketblock[sc_pow(a, b)::
|| Compute ]
@racketblock[pow(a, b)::, retaining the sign of ]
@racketblock[a::.
## ]
@racketblock[sc_powi(x, unsigned int n)::
|| Compute ]
@racketblock[x^n::, not necessarily retaining the sign of ]
@racketblock[x::.
## ]
@racketblock[sc_hypotx(x, y)::
|| Compute ]
@racketblock[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):
]
@section{list}
##
@racketblock[sc_mod(in, hi):: (floats, doubles, ints)
## ]
@racketblock[sc_round(x, quant):: (floats, doubles, ints)
## ]
@racketblock[sc_roundUp(x, quant):: (floats, doubles, ints)
## ]
@racketblock[sc_trunc(x, quant):: (floats, doubles, ints)
## ]
@racketblock[sc_gcd(a, b):: (ints, longs, floats)
## ]
@racketblock[sc_lcm(a, b):: (ints, longs, floats)
## ]
@racketblock[sc_bitAnd(a, b):: (ints)
## ]
@racketblock[sc_bitOr(a, b):: (ints)
## ]
@racketblock[sc_leftShift(a, b):: (ints)
## ]
@racketblock[sc_rightShift(a, b):: (ints)
## ]
@racketblock[sc_unsignedRightShift(a, b):: (ints)
## ]
@racketblock[sc_thresh(a, b)::
## ]
@racketblock[sc_clip2(a, b)::
## ]
@racketblock[sc_wrap2(a, b)::
## ]
@racketblock[sc_fold2(a, b)::
## ]
@racketblock[sc_excess(a, b)::
## ]
@racketblock[sc_scaleneg(a, b)::
## ]
@racketblock[sc_amclip(a, b)::
## ]
@racketblock[sc_ring1(a, b)::
## ]
@racketblock[sc_ring2(a, b)::
## ]
@racketblock[sc_ring3(a, b)::
## ]
@racketblock[sc_ring4(a, b)::
## ]
@racketblock[sc_difsqr(a, b)::
## ]
@racketblock[sc_sumsqr(a, b)::
## ]
@racketblock[sc_sqrsum(a, b)::
## ]
@racketblock[sc_sqrdif(a, b)::
## ]
@racketblock[sc_atan2(a, b):: (legacy -- use ]
@racketblock[std\::atan2::)
::
]
@section{section}
Constants
The following constants are doubles:
@section{list}
##
@racketblock[pi::
## ]
@racketblock[pi2:: = pi/2
## ]
@racketblock[pi32:: = 3pi/2
## ]
@racketblock[twopi:: = 2pi
## ]
@racketblock[rtwopi:: (1/2pi)
## ]
@racketblock[log001:: = log(0.001)
## ]
@racketblock[log01:: = log(0.01)
## ]
@racketblock[log1:: = log(0.1)
## ]
@racketblock[rlog2:: = 1/log(2)
## ]
@racketblock[sqrt2:: = sqrt(2)
## ]
@racketblock[rsqrt2:: = 1/sqrt(2)
## ]
@racketblock[truncDouble:: = 3 * 2^51 (used to truncate precision)
::
The following constants are floats:
]
@section{list}
##
@racketblock[pi_f::
## ]
@racketblock[pi2_f::
## ]
@racketblock[pi32_f::
## ]
@racketblock[twopi_f::
## ]
@racketblock[sqrt2_f::
## ]
@racketblock[rsqrt2_f::
## ]
@racketblock[truncFloat:: = 3 * 2^22 (used to truncate precision)
::
]
@section{section}
Unroll macros
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
@racketblock[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.
]
@section{definitionlist}
##
@racketblock[LOOP(length, stmt)::
|| Execute code ]
@racketblock[stmt::, ]
@racketblock[length:: times.
## ]
@racketblock[LOOP1(length, stmt)::
|| A faster drop-in alternative to ]
@racketblock[LOOP::, which assumes that ]
@racketblock[length > 0:: so a branch instruction is saved.
## ]
@racketblock[LooP(length) stmt::
|| An alternative to LOOP/LOOP1 that is more debugger-friendly. The body of the loop comes after the call to ]
@racketblock[LooP::.
## ]
@racketblock[ZIN(index)::
|| Similar to ]
@racketblock[IN::, but subtracts 1 from the pointer to correct for off-by-one errors when using ]
@racketblock[LOOP:: and ]
@racketblock[ZXP::.
## ]
@racketblock[ZOUT(index)::
|| Same as ]
@racketblock[OUT::, but subtracts 1 from the pointer to correct for off-by-one errors when using ]
@racketblock[LOOP:: and ]
@racketblock[ZXP::.
## ]
@racketblock[ZIN0(index)::
|| Alias for ]
@racketblock[IN0::.
## ]
@racketblock[ZOUT0(index)::
|| Alias for ]
@racketblock[OUT0::.
## ]
@racketblock[ZXP(z)::
|| Pre-increment and dereference ]
@racketblock[z::.
## ]
@racketblock[ZX(z)::
|| Dereference ]
@racketblock[z::.
## ]
@racketblock[PZ(z)::
|| Pre-increment ]
@racketblock[z::.
## ]
@racketblock[ZP(z)::
|| Does nothing.
## ]
@racketblock[ZOFF::
|| Return 1.
]
Reference in a new issue Copy permalink