Pdef:
Filter:
Classes | JITLib > Patterns

Pdef : EventPatternProxy : TaskProxy : PatternProxy : Pattern : AbstractFunction : Object

stream reference definition
Source: Pdef.sc
Subclasses: Pbindef

Description

Pdef registers patterns by key. All accesses to the registered patterns go through the Pdef class via that key. Registered patterns can be replaced while running. The old pattern and its replacement can automatically crossfade and the time of replacement can be quantized.

Pdef is a class that provides an interface to its superclass EventPatternProxy, keeping a reference to a stream that can be replaced while playing. One pattern may be used in many streams in different places. A change in the pattern definition propagates through all streams.

Pdef and Pdefn use separate global collections.

It can be used to store event Patterns globally. Changes in this global library have immediate effect.

For non-event patterns Pdefn is used instead. For another use of Pdef see also recursive_phrasing. Graphical overview over all current Pdefs: PdefAllGui. Overview: JITLib.

First Example

Class Methods

Pdef.all

Pdef.all = value

A global IdentityDictionary with all proxies.

Creation

Pdef.new(key, item)

Store the pattern in a global dictionary under key, replacing its pattern with the new one. If the pattern is a function, Pdef creates a PlazyEnvir internally that dynamically creates the pattern returned from the function, applying the arguments from the inevent.

Using *new(key) you can access the pattern at that key (if none is given, a default silent event is created)

Arguments:

key

An identifier for the proxy. Usually, it is a Symbol. The key transparently accesses the global IdentityDictionary.

item

An object for (re)defining the source of the proxy. If nil, the proxy is returned unmodified.

Pdef.default

From superclass: TaskProxy

Default source, if none is given. The default is an Event.silent of 1.0 beat duration.

Pdef.removeAll

From superclass: PatternProxy

Remove all proxies from the global dictionary ( *all )

Pdef.clear

From superclass: PatternProxy

Clear all proxies, setting their source to silence.

Pdef.all

Pdef.all = value

Set or return the environment ( IdentityDictionary ) that stores all Pdefs.

Pdef.defaultQuant

Pdef.defaultQuant = value

From superclass: EventPatternProxy

Set the default quantisation for new instances (default: 1.0). This can be an array [quant, phase, timingOffset, outset]

Inherited class methods

Undocumented class methods

Pdef.hasGlobalDictionary

Instance Methods

Changing the definition / setting the source

One pattern may have many streams in different places. A change in the pattern definition Pdef propagates through all streams. The change does not have to be immediate - there is a scheme to schedule when the change becomes effective: a quant and clock (like elsewhere) and a condition.

.clock

.clock = value

From superclass: PatternProxy

get or set the instance's default clock, used by -play if no other clock is specified. Defaults to TempoClock.default.

.quant

.quant = val

From superclass: PatternProxy

Set the quantisation time for beat accurate scheduling.

Arguments:

val

can be an array [quant, phase, timingOffset, outset], or just [quant, phase] etc.

.condition

.condition = value

From superclass: PatternProxy

Provide a condition under which the pattern is switched when a new one is inserted. The stream value and a count value is passed into the function.

.count(n: 1)

From superclass: PatternProxy

Create and update condition that simply counts up to n and switches the pattern then

.reset

From superclass: PatternProxy

Switch the pattern immediately (stuck conditions can be subverted by this).

.fadeTime

.fadeTime = value

From superclass: EventPatternProxy

When the synthdefs that are used contain an \amp control, the patterns are replaced by crossfading the previous with the new over this time (in beats)

.envir

.envir = dict

From superclass: PatternProxy

Set the event for the Pdef. It is used to filter the incoming stream before it is passed to the source pattern. This is similar to NodeProxy: -nodeMap. When set for the first time, the pattern is rebuilt.

.set( ... args)

From superclass: PatternProxy

Set arguments in the default event. If there is none, it is created and the pattern is rebuilt.

.map( ... args)

Map Pdefn to the keys in the event.

.clear

From superclass: PatternProxy

Set the source to nil

.endless(default)

From superclass: PatternProxy

Returns a Prout that plays the proxy endlessly, replacing nil with a default value (silent event). This allows to create streams that idle on until a new pattern is inserted.

Pdef as stream reference

A single Pdef may serve as a definition for multiple streams. These methods show how to fork off separate streams from one instance. Even if they run in different contexts, their definition may still be changed.

.fork(argClock, quant, protoEvent)

From superclass: EventPatternProxy

Play an independent stream in parallel.

Arguments:

argClock

The clock to run the substream on.

quant

can be an array of [quant, phase, offset], or a Quant value.

protoEvent

An Event to pass in that is used by the substream

Returns:

.embed(val)

From superclass: PatternProxy

Pass a value (typically an Event) into the pattern inval, and embed the Pdef in the stream.

embedInStream just like any pattern, embeds itself in stream

Pdef as EventStreamPlayer

For live coding, each Pdef also may control one instance that plays one stream off it. This is an EventStreamPlayer, accessible in the instance variable -player.

.play(argClock, protoEvent, quant, doReset: false)

From superclass: EventPatternProxy

Starts the Pdef and creates a player. (See: EventPatternProxy: -play)

.stop

From superclass: TaskProxy

Stops the player

.player

From superclass: TaskProxy

Return the current player (if the Pdef is simply used in other streams this is nil)

.pause

From superclass: TaskProxy

.resume(clock, quant)

From superclass: TaskProxy

.reset

From superclass: PatternProxy

Perform this method on the player.

.isPlaying

From superclass: TaskProxy

Returns true if player is running. If a Pdef is playing and its stream ends, it will schedule a stream for playing as soon as a new one is assigned to it. If it is stopped by stop, it won't.

Inherited instance methods

Undocumented instance methods

.copy(toKey)

.dup(n: 2)

.key

Examples

Pdef as stream reference

Pdef as EventStreamPlayer

Recursion

Pdefs can be used recursively under the condition that the stream call structure allows it. a structure like the following works:

but the following would crash, because .embedInStream is called recursively with no limit:

Quantizing and outset

When quantizing to a larger number of beats, the changes become very slow if one has to wait for the next beat. Providing an outset quant value is a way to make the change so that it appears as if it had been done at the previous grid point already. The stream is fast forwarded to the current position relative to the quant grid. Providing a number larger than zero, the next possible quant point is used as outset.

For example, if quant is 32, and one has just missed the first beat when changing the pattern, one has to wait for 32 beats until the change happens. Using an outset of 1, it is assumed that you had already changed the pattern at the first beat, the stream is fast forwarded to the time it would be at now if you had done so. The new pattern is inserted at the next beat (outset=1).

quant can be: [quant, phase, timingOffset, outset]

NOTE: This fast forwarding might create a cpu peak if the pattern is very complex/fast or quant is very long. This is hard to avoid, so it simply has to be taken into account.

Update condition

In order to be able to switch to a new pattern under a certain -condition, the instance variable condition can be set to a function that returns a boolean. Value and a count index are passed to the function. The condition is always valid for the next pattern inserted. For stuck conditions, the -reset message can be used.

As counting up (such as "every nth event, a swap can happen") is a common task, there is a method for this, called -count(n).

reset