class:: Impulse
summary:: Impulse oscillator.
related:: Classes/Blip
categories::  UGens>Generators>Deterministic


Description::
Outputs non-bandlimited single sample impulses.


classmethods::

method::ar, kr

argument::freq
Frequency in Hertz. strong::freq:: may be negative.

argument::phase
Phase offset in cycles (0..1). Staying in this range offers a slight efficiency
advantage, though phase offsets outside this range are supported and wrapped
internally.

argument::mul
The output will be multiplied by this value.

argument::add
This value will be added to the output.

Discussion::
code::Impulse:: will output a code::1.0:: on the first sample (assuming no
phase offset).

If the initial code::freq = 0::, a single impulse is output on first sample,
followed by silence until the frequency changes.

Supported rate combinations for code::(freq, phase):: are
code::(a,a)::, code::(a,k)::, code::(a,i)::,
code::(k,k)::, code::(k,i)::,
code::(i,k)::, code::(i,i)::.

code::Impulse:: is based on a wrapping phasor: phase advances on
each frame and if the phase goes out of range and is wrapped in that frame,
an impulse is output.

Internally, the strong::phase:: offset value is applied
and wrapped into range emphasis::before:: applying the phase increment
(which is determined by the strong::freq::). After this phase increment,
the trigger condition is checked. Therefore, it is the phase increment (freq)
that triggers an impulse, emphasis::not:: the phase offset.

For example, if you wanted to create an impulse train by setting
code::freq: 0:: and modulating the strong::phase:: offset directly,
code::Impulse:: would not support that.
However, a you could generate an impulse train by phase modulation using the
strong::rate:: parameter of a link::Classes/Phasor::, like this:
code::
({
	var f = 1000;
	HPZ1.ar(HPZ1.ar(
		Phasor.ar(rate: f * SampleDur.ir)
	)) > 1e-5
}.plot(0.005))
::


Examples::

code::
{ Impulse.ar(800, 0.0, 0.5, 0) }.play

{ Impulse.ar(XLine.kr(800,100,5), 0.0,  0.5, 0) }.play
::

modulate phase:
code::
{ Impulse.ar(4, [0, MouseX.kr(0, 1)], 0.2) }.play;
::

an Impulse with frequency 0 returns a single impulse:
code::
SynthDef(\imp, { OffsetOut.ar(0, Impulse.ar(0)); FreeSelf.kr(Impulse.kr(0)); }).add;
fork { (1 / (1..60).scramble).do { |dt| Synth.grain(\imp);  dt.wait } };
::
