The preceding sections showed how to use Streams and Patterns to generate complex sequences of values for a single parameter at a time.
This section covers Environments and Events, which are used to build a symbolic event framework for patterns, allowing you to control all aspects of a composition using patterns.
An Environment is an IdentityDictionary mapping Symbols to values. There is always one current Environment which is stored in the currentEnvironment class variable of class Object.
Symbol and value pairs may be put into the current Environment as follows:
and retrieved from the current Environment as follows:
The compiler provides a shorthand for the two constructs above.
is equivalent to:
and:
is equivalent to:
Environment has a class method make which can be used to create an Environment and fill it with values. What make does is temporarily replace the current Environment with a new one, call your function where you fill the Environment with values, then it replaces the previous current Environment and returns you the new one.
The instance method use lets you temporarily replace the current Environment with one you have made. The use method returns the result of your function instead of the Environment like make does.
There is also a use class method for when you want to make and use the result from an Environment directly.
It is possible to call a Function and have it look up any unspecified argument values from the current Environment. This is done with the valueEnvir and valueArrayEnvir methods. These methods will, for any unspecified argument value, look in the current Environment for a symbol with the same name as the argument. If the argument is not found then whatever the function defines as the default value for that argument is used.
Here is a somewhat contrived example of how the Environment might be used to manufacture SynthDefs. Even though the three functions below have the freq, amp and pan args declared in different orders it does not matter, because valueEnvir looks them up in the environment.
The class Event is a subclass of Environment. Events are mappings of Symbols representing names of parameters for a musical event to their value. This lets you put any information you want into an event.
The class getter method default retrieves the default prototype event which has been initialized with values for many useful parameters. It represents only one possible event model. You are free to create your own, however it would be good to understand the one provided first so that you can see what can be done.
A prototype event is a default event which will be transformed by the streams returned by patterns. Compositions produced by event patterns are created entirely from transformations of copies of a single protoEvent.
The patterns discussed in parts 2 and 3 are known as "value patterns" because their streams return a single value for each call to next. Here we introduce "event patterns" which once turned into streams, return an Event for each call to next.
The class Pbind provides a bridge between value patterns and event patterns. It binds symbols in each event to values obtained from a pattern. Pbind takes arguments in pairs, the first of a pair being a Symbol and the second being a value Pattern. Any object can act as a Pattern, so you can use constants as the pattern ( see \amp in the example below ).
The Pbind stream returns nil whenever the first one of its streams ends.
An event stream is created for a Pattern by sending it the asStream message. What Pbind does is to produce a stream which puts the values for its symbols into the event, possibly overwriting previous bindings to those symbols:
When calling Pattern: -play an EventStreamPlayer is automatically generated which handles scheduling as well as passing the protoEvent into the event stream.
The class EventStreamPlayer is a subclass of PauseStream. A PauseStream is just a wrapper for a stream allowing to play, stop, start it, etc...
EventStreamPlayers are initialized using the event stream returned by Pbind-asStream, as well as with a protoEvent. The EventStreamPlayer passes in a protoEvent, at each call to next on the Pbind stream. The Pbind stream copies the event to pass down and back up the tree of pattern streams so that each stream can modify it.
An EventStreamPlayer is itself a stream which returns scalars (numbers) which are used by the clock to schedule its next invocation. At every call to EventStreamPlayer-next by the clock, the player gets its delta values by querying the Event after it has been returned by the Pbind stream traversal.
In SC2, you called asEventStream on an Pattern and you'd get a stream which actually returned events.
In SC3, if you want an event stream proper you call asStream on the Event Pattern. This will give you a stream of events which you can then use to initialize an EventStreamPlayer object. You don't however need to worry about that because it is usually done for you in Pattern's play method. Also changed is that you do not pass in your protoEvent through the asStream method. It is passed in for you by the EventStreamPlayer at each call to next on the stream.
Here you can see what the stream returned from a Pbind looks like.
Here is an example with more bindings.
The ListPatterns discussed in part 3 can be put around Event Streams to create sequences of Event Streams.
To go to the next file: Understanding Streams, Patterns and Events - Part 5