Merge pull request #506 from andrewcsmith/patch-2
[supercollider.git] / HelpSource / Classes / FreeSelfWhenDone.schelp
blobc3863b9ba71fa3c56f6b0f5733060bcfe8adc4e3
1 class:: FreeSelfWhenDone
2 summary:: Free the enclosing synth when a UGen is finished
3 related:: Classes/Done, Classes/PauseSelfWhenDone, Reference/UGen-doneActions
4 categories::  UGens>Synth control
6 Description::
8 Some UGens set a 'done' flag when they are finished playing.
9 FreeSelfWhenDone will free the enclosing synth when this flag is set to true.
11 See link::Classes/Done:: for a complete list of these UGens.
13 Note that many of these UGens have doneActions, which are another way of accomplishing the same thing. See link::Reference/UGen-doneActions:: for more detail.
15 note:: One must be careful when using binary operations on UGens with done flags, as these will return a link::Classes/BinaryOpUGen::, and thus prevent the done flag from being accessible. See example below. ::
17 classmethods::
18 private:: categories
20 method::kr
22 argument::src
24 the UGen to check for done.
26 examples::
27 code::
28 s.boot;
30 // simple example
32 { var env;
33 env = Line.kr(0, 1, 1);
34 FreeSelfWhenDone.kr(env); // free synth at end of line
35 SinOsc.ar(200, 0, 0.5) * env
36 }.play;
39 // the previous example works, because FreeSelfWhenDone operates on the Line
40 // this version won't work
42 { var env, output;
43 env = Line.kr(0, 1, 1);
44 output = SinOsc.ar(200, 0, 0.5) * env;
45 output.postln; // output is a BinaryOpUGen, which has no 'done' flag
46 FreeSelfWhenDone.kr(output); // won't ever be done
47 output
48 }.play;
51 // record for four seconds
52 b = Buffer.alloc(s, 44100 * 4.0, 1);
54 SynthDef("help-RecordBuf",{ arg out=0,bufnum=0;
55         var formant, recbuf;
56         formant = Formant.ar(XLine.kr(400,1000, 4), 2000, 800, 0.125);
57         recbuf = RecordBuf.ar(formant, bufnum, recLevel: Line.kr(1, 1), loop: 0);
58         // The RecordBuf doesn't loop, so you can check it for 'done' status
59         FreeSelfWhenDone.kr(recbuf);
60 }).play(s,[\out, 0, \bufnum, b]);
63 // play it back
65 SynthDef("help-RecordBuf play",{ arg out=0,bufnum=0;
66         var playbuf;
67         playbuf = PlayBuf.ar(1,bufnum);
68         FreeSelfWhenDone.kr(playbuf); // frees the synth when the PlayBuf is finished
69         Out.ar(out, playbuf);
70 }).play(s,[\out, 0, \bufnum, b]);