Using Expressions in Layers

To set up an Expression, right-click the property you want to control in the Layer editor.

This will open up the Metafield which shows min/max/step, which allows you to edit the limits of the property and the value step used while animating.

Below the min/max/step properties is a field called Expression, which initially contains a single word: self. This is the expression we will be editing.

The default expression: self

self is a special variable defined in the context of Layer expressions. It is not valid or may mean something different in other places which accept expressions. self refers to the normal animated value of the property the expression is controlling. The default expression being self means that by default the value set on the Layer property is used as-is, without modification.

self is a number for numeric properties, and text for text properties.

By deleting the value completely, disguise will auto-fill self as the value of the expression. Therefore, simply deleting the text in the Expression field is a quick way of resetting back to the default behaviour of using the Layer property as-is.

Using self in expressions

self, like many other variables can be built into more complex expressions. A simple expression might be self * 2, which doubles the animated value of the property.

Other variables in layer expressions

Some variables are defined by the system for convenience. In the case where the expression is evaluated by a layer, the following variables are available:

• time - track time in seconds since the start of the track.
• self - the keyframed value, as described above.
• self.min - minimum value for this field.
• self.max - maximum value for this field.

Example: Emergency layer fade down

A common use case is to use an expression for the brightness property on a Layer. For example, it may be necessary to have a fader or other live control have an emergency cut-out option for live video. In this example, we will say that this control is implemented using OSC, but could be done with any live input protocol supported by disguise.

self * (1 - osc:video.emergency_cut_out)

In this example, we take the normal animated value of the property (self) and multiply it by 1 - the value sent on OSC address /video/emergency_cut_out. Normally, that OSC value would be 0, and so 1 - 0 is 1 and self * 1 is just self, so normal animated values are respected.

However, if /video/emergency_cut_out is set to 1, then the expression will evaluate to self * 0 which, since any number multiplied by 0 is 0, would ensure the brightness of the layer is 0 and therefore will not be shown.

Using expressions to control layers

Warning

Warning: Expressions need special handling for Resource names that have spaces in them, for example a Layer called “video explosions”. Expressions require the user to refer to it as “video_explosions” instead (replacing the space with an underscore _).

Names can only contain the characters a-z A-Z 0-9 _.

This can cause conflicts when two Resources share the same name after normalisation, and it may be necessary to rename layers to ensure they are uniquely identifiable if they are being used in expressions.

It is possible to have designer write simple linking expressions automatically. The method is to hold the Alt key and drag the mouse from the desired value in the designer GUI to the layer field you wish to control. It is possible to do this from most places in the GUI, including other layers. (To open multiple layers at the same time, hold Ctrl and click on the Layers you wish to open simultaneously.) See Creating a connection using mouse drag for more information.

Example: Link brightness between multiple layers

Open an editor for the 2 layers the user wishes to link, and Alt+Drag from one layer’s brightness property to the other’s. Designer will write an expression referring to the first layer’s brightness into the second (destination) layer.

From that point on, animation and edits of the layer the user dragged from controls both layers. The process can be repeated (we recommend dragging from the same first layer every time, not in a chain.) to control as many layers as the user desires.

Note that layer references are only valid for the period of time that the layer is active on the timeline. Attempting to access a layer property for a layer which is not currently under the playhead will fail. This is because there is no coherent value for a layer property outside its timeline extents.

Example: Using a video layer frame number to animate brightness

Video Layer’s frameNumberDisplay provides the current frame readout at the top of the video layer. This isn’t something the user needs to remember - instead, open the Layer editor for a video module named video. Alt + Drag from the frame readout at the top of the layer, and drop it onto the brightness property of another layer (e.g. a chevron layer.)

This will result in the following expression being written into the brightness property of the Chevron layer: module:video.frameNumberDisplay.

That property can then be used as a variable by the expression. For example, set the brightness to 0 until the video reaches frame 50, then snap to 1: if(module:video.frameNumberDisplay < 50, 0, 1)

Or to smoothly fade up over the first 50 frames: min(1, lerp(0, 1, module:video.frameNumberDisplay / 50.0))

Layer prefixes

Layer prefixes make the job of targetting a potentially unknown range of values expected by a given field easier. They are used by the built-in alt+drag functionality for building readable expressions from common components like DMX or MIDI inputs.

The field range is available as variables in self.min to self.max.

• limit:: - Limits result to the field range. This is equivalent to clamp(expr, self.min, self.max)
• scale:: - Scales 0 - 1 values to the field range, ignoring limits. This is equivalent to lerp(self.min, self.max, expr)