help: Env circle methods - update language, add notes and examples

supercollider · Jan 14, 2025 · 91a83b3 · 91a83b3
1 parent 15d1cb9
commit 91a83b3
Showing 1 changed file with 45 additions and 10 deletions.
diff --git a/HelpSource/Classes/Env.schelp b/HelpSource/Classes/Env.schelp
@@ -455,24 +455,45 @@ Env.cutoff(1, 1, \sine).test(2).plot;
 ::
 
 method::circle
-Creates a new envelope specification which cycles through its values. Unlike the link::#*new:: method, the strong::levels::, strong::times:: and strong::curve:: arrays are all the same size. The loopback time and curve are the last element of those arrays.
+Creates a new envelope which, when used by an link::Classes/EnvGen::, cycles through its values.
 
-For making a instantiated envelope cyclic, you can use the instance method link::#-circle::
+For making an already-created envelope cyclic, you can use the link::#-circle:: instance method, which takes the looparound time and curve as arguments.
 
 argument::levels
 The levels through which the envelope passes.
 
 argument::times
-The time between subsequent points in the envelope, which may be a single value (number), or an array of them. If too short, the array is extended.
+The time between subsequent strong::levels:: in the envelope. The last value is the looparound time.
+The array size of strong::times:: should be the same size of the strong::levels:: array.
 
 argument::curve
-The curvature of the envelope, which may be a single value (number or symbol), or an array of them.  If too short, the array is extended.
+The curvature of the envelope segments. The last value is the looparound curve. See link::#*new:: for valid values.
+The array size of strong::curve:: should be the same size of the strong::levels:: array.
 
+note::
+If a single value is given for strong::times:: or strong::curve::, or if the array is too short, it will be extended by wrapping around the given values
+::
 
 discussion::
+note::
+
+The circular code::Env:: must be instantiated inside the function used to construct the link::Classes/SynthDef::. It will not work not work if it is instantiated outside the function, e.g. passed in as a variable.
+
+Due to the internal initializing the cyclic behavior, there is a one-sample delay of the envelope.
+::
+
 code::
-// Plot the envelope
-{ EnvGen.kr(Env.circle([0.1, 1, 0.3], [0.01, 0.03, 0.06])) }.plot(0.4)
+( // Plot the envelope using *circle and -circle
+var loopBackTime = 0.06;
+{ [
+	EnvGen.kr(
+		Env.circle([0.5, 1, 0.3], [0.01, 0.03, loopBackTime])
+	),
+	EnvGen.kr(
+		Env.new([0.5, 1, 0.3], [0.01, 0.03]).circle(loopBackTime)
+	)
+] }.plot(0.1 * 4 - 0.01).plotMode_(\dlines)
+)
 
 // A sound example
 { SinOsc.ar(EnvGen.kr(Env.circle([0, 1, 0], [0.01, 0.5, 0.2])) * 440 + 200) * 0.2 }.play;
@@ -682,17 +703,31 @@ e.totalDuration;
 ::
 
 method::circle
-Declare the code::Env:: as circular, so that when used with link::Classes/EnvGen::, the code::Env:: is looped through cyclically.
+Declare the code::Env:: as circular so that, when used with link::Classes/EnvGen::, the code::Env:: is looped through cyclically.
+
+You can create a circular code::Env:: directly with the link::#*circle:: class method.
+
+argument:: timeFromLastToFirst
+The time to loop around from the last to the first level of the code::Env::.
+If not specified, the looparound time is immediate (one sample).
 
-Note that if strong::timeFromLastToFirst:: is not specified, the loopback time is immediate (one sample). Create a circular code::Env:: directly with the class method link::#*circle::.
+argument:: curve
+The curvature of segment connecting the last and first level of the code::Env::.
+Possible values are the same as in the link::#*new:: strong::curves:: argument.
 
 discussion::
+note::
+The circular code::Env:: must be instantiated inside the function used to construct the link::Classes/SynthDef::. It will not work not work if it is instantiated outside the function, e.g. passed in as a variable.
+
+Due to the internal initializing the cyclic behavior, there is a one-sample delay of the envelope.
+::
+
 code::
 // No args: loopback is immediate
-{ EnvGen.kr(Env([0.1, 1, 0.5], [0.01, 0.03]).circle) }.plot(0.2).plotMode_(\points)
+{ EnvGen.kr(Env([0.1, 1, 0.5], [0.01, 0.03]).circle) }.plot(0.2).plotMode_(\dlines)
 
 // With loopback time and curve specified
-{ EnvGen.kr(Env([0.1, 1, 0.5], [0.01, 0.03]).circle(0.05, \sin)) }.plot(0.2).plotMode_(\points)
+{ EnvGen.kr(Env([0.1, 1, 0.5], [0.01, 0.03]).circle(0.05, \sin)) }.plot(0.2).plotMode_(\dlines)
 
 ( // Looping frequency modulation
 {