Generators
=======

Abstract
--------

This document describes how GENERATOR extensions to audiolib.js should be designed, and what functionality they should provide.
GENERATOR extensions are used as a means to be generate buffers or samples.

   *PLEASE NOTE*: This spec is a draft and a work in progress, and should not be referenced to as anything else. However, as such it does already provide some guidelines and recommendations that should not be disregarded. For suggestions of improvements, fork, blame or raise an issue.

GENERATOR
------

GENERATOR is a class interface for a single/multi-channel source, that operates on a "single sample out" basis. The GENERATOR interface automatically provides the GENERATOR with means to do buffer-based generating in such a manner that the usage as buffer-based source is automatically provided, and is not in the hands of the plugin developer to implement. The GENERATOR interface is specified as follows:

```

class interface GENERATOR
{
	public void generate();
	public Float32 getMix(Optional Int8 channelNumber);
	public __constructor__(sampleRate, /* plugin specific arguments */);

	/* Functionality provided in the GENERATOR class automatically, does not concern the plugin developer. */
	public String name;
	public readonly String fxid;
	public readonly String type;
	public readonly Boolean sink;
	public readonly Boolean source;
	public Float32 mix;
	public AudioBuffer append(AudioBuffer buffer, Int8 channelCount);
}

```

 ``` generate ``` should should make the GENERATOR advance it's phase position by a single sample.

 ``` getMix ``` should return output of the GENERATOR at the current phase, ``` channelNumber ``` argument determines which channel's output to return, if omitted, default to 0. Mono GENERATORs should ignore this argument.

 ``` __constructor__ ``` is not an actual property of the GENERATOR, but describes how the GENERATOR constructor should be created. The constructor should take sample rate as the first argument, the rest of the arguments are freely specified by the plugin author.


 ``` name ``` or ``` fxid ``` is the name of the GENERATOR. You should always refer to ``` fxid ``` when trying to identify the effect via these means, ``` name ``` can be specified for individual instances.

 ``` type ``` is a string containing the type of the GENERATOR, and should always be 'generator' for GENERATOR.

 ``` sink ``` is a boolean indicating whether the GENERATOR is a sink, and should always be false for GENERATOR, otherwise see [EFFECT](https://github.com/jussi-kalliokoski/audiolib.js/blob/master/specs/effects.md).

 ``` source ``` is a boolean indicating whether the GENERATOR is a source, and should always be true for GENERATOR.

 ``` mix ``` is a Float32 value determining the volume of the GENERATOR. Zero (0.0) indicates the GENERATOR should be silent, whereas One(1.0) indicates a full volume. Used for interfacing with buffer creation. Default value is 1.0.

 ``` append ``` fills the provided ``` buffer ``` with samples generated by the GENERATOR, according to the ``` channelCount ``` specified.


Integration
-----------

Integration is done with the ``` audioLib.generators() ``` function. Integration makes instances of GENERATOR instances of the internal GeneratorClass, provides the additional functionality described in the GENERATOR interface and attaches the GENERATOR to ``` audioLib.generators ``` by the name specified.

```

Generator audioLib.generators(String name, Function __constructor__, optional Object prototype);

```

 ``` name ``` is the name to attach the GENERATOR to ``` audioLib.generators ``` with, and will also be applied as the ``` fxid ``` and default ``` name ``` of the GENERATOR.

 ``` __constructor__ ``` is the constructor of the GENERATOR. If not specified, the function does nothing but return a property of ``` audioLib.generators ``` by the name specified by ``` name ``` argument.

 ``` prototype ``` is an object that the default GENERATOR prototype will be extended with. If not specified, will default to the prototype property of ``` __constructor__ ```

Example
-------

Here is the code for an example GENERATOR of the name 'SemiClock', that creates a clock signal at half the samplerate.

```javascript

audioLib.generators('SemiClock', function (sampleRate){
	this.sampleRate = sampleRate;
}, {
	prevSample: 0.0,
	generate: function(sample){
		this.phase = + !this.phase;
	},
	getMix: function(){
		return this.phase;
	},
	phase: 0
});

```