Merge branch 'main' of https://github.com/Bubobubobubobubo/Topos

src/documentation/patterns/generators.ts

@@ -6,9 +6,48 @@ export const generators = (application: Editor): string => {
   return `
 # Generator functions
 
+JavaScript <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator" target="_blank">generators</a> are powerful functions for generating value sequences. They can be used to generate melodies, rhythms or control parameters.
+
+In Topos generator functions should be called using the <ic>cache(key, function)</ic> function to store the current state of the generator. This function takes two arguments: the name for the cache and the generator instance. 
+
+Once the generator is cached the values will be returned from the named cache even if the generator function is modified. To clear the current cache and to re-evaluate the modified generator use the **Shift+Ctrl+Backspace** shortcut. Alternatively you can cache the modified generator using a different name.
+
+The resulted values can be played using either <ic>pitch()</ic> or <ic>freq()</ic> or as Ziffers patterns. When playing the values using <ic>pitch()</ic> different scales and chained methods can be used to alter the result, for example <ic>mod(value: number)</ic> to limit the integer range or <ic>scale(name: string)</ic> etc. to change the resulting note.
 
 ${makeExample(
-  "More complex function generating chaotic frequencies",
+"Simple looping generator function",
+`
+function* simple() {
+    let x = 0;
+    while (x < 12) {
+        yield x+x;
+        x+=1;
+    }
+}
+
+beat(.25) && sound("triangle").pitch(cache("simple",simple())).scale("minor").out()
+`,
+true,
+)};
+
+${makeExample(
+"Infinite frequency generator",
+`
+    function* poly(x=0) {
+     while (true) {
+        const s = Math.tan(x/10)+Math.sin(x/20);
+        yield 2 * Math.pow(s, 3) - 6 * Math.pow(s, 2) + 5 * s + 200;
+        x++;
+     }  
+    }
+    
+    beat(.125) && sound("triangle").freq(cache("mathyshit",poly())).out()
+`,
+true,
+)};
+
+${makeExample(
+  "Truly scale free chaos inspired by Lorentz attractor",
   `
   function* strange(x = 0.1, y = 0, z = 0, rho = 28, beta = 8 / 3, zeta = 10) {
     while (true) {
@@ -33,5 +72,48 @@ ${makeExample(
   true,
 )};
 
-`;
+## OEIS integer sequences
+
+To find some inspiration - or to enter into the void - one can visit <a href="https://oeis.org/" target="_blank">The On-Line Encyclopedia of Integer Sequences (OEIS)</a> to find some interesting integer sequences. 
+
+Many of the sequences are implemented by <a href="https://github.com/acerix/jisg/tree/main/src/oeis" target="_blank">JISG</a> (Javascript Integer Sequence Generators) project. Those sequences can be referenced directly with the identifiers using the cache function.
+
+One of these implemented generators is the Inventory sequence <a href="https://github.com/acerix/jisg/blob/main/src/oeis/A342585.ts" target="_blank">A342585</a> made famous by <a href="https://www.youtube.com/watch?v=rBU9E-ZOZAI" target="_blank">Neil Sloane</a>.
+
+${makeExample(
+    "Inventory sequence",
+    `
+    rhythm(0.5,[8,7,5,6].bar(4),9) :: sound("triangle")
+    .pitch(cache("Inventory",A342585))
+    .mod(11).scale("minor")
+    .adsr(.25,.05,.5,.5)
+    .room(2.0).size(0.5)
+    .gain(1).out()
+    `,
+    true,
+    )};
+
+## Using generators with Ziffers
+
+Alternatively generators can be used with Ziffers to generate longer patterns. In this case the generator function should be passed as an argument to the ziffers function. Ziffers patterns are cached separately so there is no need for using **cache()** function. Ziffers expects values from the generators to be integers or strings in ziffers syntax.
+
+${makeExample(
+    "Ziffers patterns using a generator functions",
+`
+function* poly(x) {
+    while (true) {
+      yield 64 * Math.pow(x, 6) - 480 * Math.pow(x, 4) + 720 * Math.pow(x, 2);
+      x++;
+    }
+  }
+  
+z0(poly(1)).noteLength(0.5).semitones(2,2,3,2,2,2).sound("sine").out()
+z1(poly(8)).noteLength(0.25).semitones(2,1,2,1,2,2).sound("sine").out()
+z2(poly(-3)).noteLength(1.0).semitones(2,2,2,1,3,2).sound("sine").out()
+`,
+    true,
+  )};
+
+
+`
 };

src/documentation/patterns/ziffers/ziffers_syncing.ts

@@ -12,14 +12,14 @@ Ziffers patterns can be synced to any event by using **cue**, **sync**, **wait**
 
 The <ic>cue(name: string)</ic> methods can be used to send cue messages for ziffers patterns. The <ic>wait(name: string)</ic> method is used to wait for the cue message to be received before starting the next cycle.
 
-    ${makeExample(
-        "Sending cue from event and wait",
-        `
-        beat(4.0) :: sound("bd").cue("foo").out();
-        z1("e 0 3 2 1 2 1").wait("foo").sound("sine").out();
-        `,
-        true,
-    )}
+${makeExample(
+"Sending cue from event and wait",
+`
+beat(4.0) :: sound("bd").cue("foo").out()
+z1("e 0 3 2 1 2 1").wait("foo").sound("sine").out()
+`,
+true,
+)}
 
 The <ic>sync(name: string)</ic> method is used to sync the ziffers pattern to the cue message.