Effects/FX

Introduction

Effects are the parts which are connecting the Table and its TableElelement objects to the Toy objects in the Cabinet object. While toys are thought to be relatively stupid and just capable of doing a few simple things (e.g. set a RGB LED to a specific color), effects should do the more complex operations (e.g. dimming the color of a LED from one color to another).

Effects are triggered by TableElement objects (e.g. a switch or a lamp) changing its state or value and also by the Table itself when the Table is started.

DOF contains two types of effects:

• Toy effects are effects controlling a toy. Typically they hold a reference to one or severeal toys which are controlled by the effect.
• Effect effects are effects which are controlling other effects. Typically effect effects are holding references to one or several target effects.

Effect types

Stacking/chaining of effect effects

Effects can be chained resp. stacked to achive more complex behaviour than the standard behaviour of effects.

Effect effects (effects which troger other effects) are used for chaining and any number of effects can be chained. The last effect in a chain of effects is always a toy effect which controls one or several instances of a toy objects.

Example 1

Stacked effects example 1

In this example, the first effect is a delay effect (2), which will forward the received trigger signal (1) from the table element after a specified delay. The output of the delay effect (2) triggers a first blink effect (3) which a long blink period. The output of the first blink effect (3) triggers a second blink effect (4) with a much short blink period. This will create short blinks within the long blinks of the first blink effect (3). Finnaly the output of the second blink effect (4) triggers the finaly toy effect, in this case a RGBAFadeOnOff effect (5) which will fade in and out the led depending on the received input signal (4).

Example 2

Stacked effects example 2

In the second example, a short trigger pluse from a table element (1) triggers a duration effect (2). The output of the duration effect (2) will trigger a blink effect (3). This will create blinking for the specified duration whenever the first effect in the chain receives a trigger signal. The finaly RGBAFadeOnOff effect (4) will fade in and out the color of the target toy, in this case a RGB-Led, depending on the output signal of the previous toy (3). So finnaly, we get a fading blinking for the duration specified in the second effect, whenever a trigger pluse is received by the effect chain.

Built in effects

Please read the page on Built in Effects for details and config samples on the various effect classes available in the framework.

Custom effects

The DirectOutput framework can easily be extended to support your own custom effects.

All effects must implement the _IEffect__ interface so they are recognized by DOF as effects and must have a globaly unique name (not only within the namespace).

Depending on the the of effect you want to create, it is best if you inherit one of the abstract effect base classes for your implementation. These base classes take care of all the basic tasks for the effects.

Implementation guidelines for effects

• Effects have to be coded in C# (not that difficult to learn).
• All effects must implement the IEffect interface. This interface specifies some methods, properties and events which have to be implemented for every effect.
• Try to inherit one of the abstract base classes in the FX namespace and its subnamespaces.
• Define a globaly unique name (not only unique within its namespace) for your effect class. This name will also be used when a config file is loaded or saved. If the name is not unique loading or saving will probably fail.
• Ensure that your effect class is XMLSerializable. As a rule of thumb, your class must implement a paramaterless constructor and all settings for the effect have to be available through public properties.
• Put your effects into a meaningfull subnamespace of the FX namespace. If no suitable subnamespace exists, create a new subnamespace.
• Be fault tolerant and handle all errors if necessary. In particular keep care that no exceptions are thrown, if the toy which is specified by its name in your effect is of a wrong type. If a effect throws a exception, it will get deactivated by DOF for the session.
• If your effect needs timed events, register for the alarm function of the Alarms object in the Pinball object if possible. This will ensure that the necessary update functions are called and at the same time make sure that no unnessecary update calls to output controllers are triggered.
• Make your code fast! Try to resolve as many references and precalculate as many things as possible in the Init method of the effect.
• Implement your own finish method, if your effect uses the Alarm methods of the Pinball object, to unregister all alarms that might be schedule for the effect. Finish is also a good place to get rid of all allocated resources and to unregister the effect from events it might has registered to earlier.
• Comment your code! At least the public methods and properties of your effect should be properly documented with XML comments. The documentation of DOF is automatically generated from the comments in the source files.
• to be continued.....