The “DMX Patch” field of an effect definition is one line of computer code that translates the parameters of the effect into the DMX channels of the fixture, taking into account the duration of the effect, the angle of the trajectory, and other parameters if applicable.  You can unhide the DMX Patch field in the effects window to examine it.  Here are a few examples of DMX patches for certain kinds of effects.

A red flash of an EasyDancing par light has the DMX patch,

[beginEndPatch 0 32 0 1 255 255 2 0 0 3 0 0 5 0 0 6 0 0]

A red flash of the light beam of a Tomshine moving head spotlight fixture has the DMX patch,

[setupBeginEndPatch 1000 0 :pan540 :pan540 :pan540 1 :rTilt230 :rTilt230 :rTilt230 2 0 0 0 3 0 255 0 5 12 12 12]

A “Move-To” animated light beam for the Tomshine moving head spotlight fixture has the DMX patch,

[setupBeginEndPatch :effectiveSetupPlus1000Ms 0 :pan540 :pan540 :pan540 1 :rTilt230 :rTilt230 :rTilt230 2 :spdFrmESetupF1 :spdFrmESetupF1 :spdFrmESetupF1 3 255 255 0 5 12 12 12 :defineFunc1 :power 250 1 1.6]

These three examples cover a range of simple to complicated DMX patches.  The reason the first DMX patch is simple is that par lights don’t have very much interaction with the user interface.  A par light doesn’t animate; it just turns on and off in various colors, and maybe strobes.  Thus the user interface for adding a flash of a red par light to a show involves nothing more than inserting the effect and possibly changing its duration on the timeline.   The numbers after the term beginEndPatch in the first example are the instructions to set the DMX channels to turn the light on with the color red for the duration of the effect.

The second example is more complicated because after inserting a light beam effect for a moving head fixture, the user can drag the dotted line trajectory in the 3D view or use functions like “Fan” to change the angle of the light beam.  The DMX patch has to translate the angle of the dotted line that the user specified into the DMX channel values for the moving head fixture, which are typically specified as pan and tilt values.   The extra parameters after the setupBeginEndPatch term provide for that translation.

The term setupBeginEndPatch also introduces the concept of “setup time”.  A moving head light fixture doesn’t move instantaneously, so if you want to flash a beam at a particular angle at time T, then you need to start moving the head angle of the fixture prior to T so it is pointing the right direction at the time you want it to flash.  The setupBeginEndPatch specifies the DMX channel values that apply at the beginning of the setup time, and also at the beginning of the visual effect (the effect time), and also at the end of the visual effect (the effect time plus the effect duration).  The concept of setup time also applies to gobos and color wheels, which need to rotate to the desired angles in advance of the effect turning on.

The first parameter of the setupBeginEndPatch is the “ideal setup time”, which may be a constant number of milliseconds or may refer to a setup time definition like nominal setup time or effective setup time.  The “nominal setup time” refers to the event’s “Prefire” column in the script.  In DMX patches, the nominal setup time is mainly used in the calculation of the effective setup time as the maximum lookback interval for a Move-To event to connect to a preceding event that defines the “from” angle.  The “effective setup time” is the shorter of (a) the nominal setup time and (b) the time interval between the effect time of the event and the effect time of the nearest preceding event that whose VDL does not contain the keyword “Modifier”.  The VDL keyword “Modifier” is used for effects like “With Strobing” that modify other effects but do not have a visual appearance on their own.  The “per-channel setup time” is calculated for each channel of the DMX patch independently.  For each channel, the per-channel setup time is the shorter of (a) ideal setup time, and (b) the time interval between the effect time of the event and the event’s backstop from the nearest preceding event that whose DMX patch specifies a value for the channel.  An event’s “backstop” from its previous event is the previous event’s effect time if the event (not the previous event) has a non-zero nominal setup time; and is the previous event’s end time otherwise.  The “nominal duration” is the value of the Duration field in the Finale 3D event with which the DMX command is associated.

The third example specifies an animated light beam that moves to the angle that the user specifies by angling the dotted line trajectory in the 3D view, animating from the angle specified by the dotted line of the effect preceding it.  Based on the amount of time in between the preceding effect and the Move-To effect, and the difference of the dotted line trajectory angles, the fixture’s moving head will need to rotate during that time at a particular speed to reach the goal angle at just the right time.  The additional parameters in this third DMX patch example define the formulas for calculating the motor speed DMX channel of the fixture.

Triggering fixtures’ pre-defined macros

Some fixtures, like the Explo X2 Wave Flamer, have pre-defined macros, or programmed sequences, that are triggered by initially setting a DMX channel specifying the macro number and then setting the DMX channel to turn the ignition ON to play the macro.  To re-trigger the macro to play again, the DMX channel of the ignition must be turned OFF before being turned on again.

If pre-defined macros are scripted back to back, there is no time between the end of one event and the beginning of the next event to turn off and on the ignition.  For the next event to trigger successfully, the ignition channel must be turned off prior to the end of the earlier event.  The setupBeginEndPatch provides a mechanism to guarantee the ignition channel turns off between events, as illustrated by this DMX Patch for one of the pre-defined macros of the Explo X2 Wave Flamer,

[setupBeginEndPatch 100 1 0 0 0 2 0 255 0 3 0 0 0 4 :customPartFieldExploX2 :customPartFieldExploX2 :customPartFieldExploX2]

The effect with this DMX Patch must also have a non-zero “Prefire” value so that the “backstop” definition relating to the “per-channel setup time” is the beginning of the previous event, not the end of the previous event.  The Explo X2 Wave Flamer’s ignition DMX channel is channel offset 2.  In this example patch, the ignition channel at offset 2 will be set to zero at “per-channel setup time” before  to the start of an event (100 ms) even if that time overlaps the duration of the previous event.

In contrast with the pre-defined macros for which turning off and on the ignition is vitally important, effects that employ setup time only if it is available after the end of the previous event, like the red flash example above, should have a zero “Prefire” which causes the “backstop” to refer to the end of the previous event, not the beginning.

Functions

The examples illustrate the beginEndPatch and setupBeginEndPatch functions.  There are only four DMX patch functions in total, shown in Table 1.  All of these functions have same basic syntax: they are the first term in a list of terms in square brackets.  The remaining terms in the list are the parameters to the function.  The first example above had a beginEndPatch term followed by 18 parameters.

Table 1 – Functions used in DMX Patches

Parameters

The parameters available for DMX Patches are a mixture of general parameters and specialized parameters that support various calculations.  If you are adding effects for a fixture that is not yet supported in Finale 3D, you may run across a need for a new calculation to support your fixture.  If so, please email the Finale support team to have it added to the DMX Patch language.

The most general parameters are just numbers.  Channel offsets are integers beginning with 0.  Channel values are integers from 0 to 255.  All other parameters, shown in Table 2, are symbols beginning with colons that evaluate to calculated values for channel offsets, channel values, or durations.  As a simple example, the parameter :duration10 evaluates to the duration of the effect in 10ms units (hundredths of a second).  If the DMX Patch requires a channel to be set to the duration in hundredths of a second, this parameter produces the right number.

The parameter :duration500MsTo2500Ms is also a duration parameter but its calculation maps effect durations from 500ms to 2500ms to integers 0 to 255 (clamped at the ends).  As you can guess from these two examples, many of the calculated parameters are specialized for the needs of of specific fixtures.  If a fixture requires a duration in the range 0-255 for effect durations 500ms to 2500ms, the :duration500MsTo2500Ms parameter is just right.  If the requirement were for 1000ms to 2500ms then a different parameter would be required, and if it weren’t yet defined then you would need to reach out to Finale to have it added.

The DMX Patch has a maximum length of 256 characters.   That’s barely enough for some of the most complicated effects, so some of the long parameter names in Table 2 have optional shorter synonyms that take fewer characters.  The third example above uses :spdFrmESetupF1 in place of :speedFromEffectiveSetupAndFunc1 to save space.

Table 2 – Parameters used in DMX Patches

Optional parameters

The functions of Table 1 are followed by a list of required parameters and optional parameters following the required parameters.  The optional parameters, which begin with :defineFunc1 or :defineFunc2, define functions that can be referred to by required parameters, such as :speedFromEffectiveSetupAndFunc1.  The purpose of the function is to provide a user-defined calculation for a motor speed channel value of a moving head fixture.

The parameter :speedFromEffectiveSetupAndFunc1 does just that — it evaluates to the DMX channel value for motor speed that will make the head rotate at the correct rotational velocity in degrees per second to cover the Move-To angle over the effective setup period of time.  Unfortunately, the motor speed DMX channel values of most fixtures do not correspond to rotational velocities in a simple linear equation, so the only way to figure out what the correspondence actually is is to measure it, as in Figure 1.

Figure 1 – Motor speeds for Tomshine moving head fixtures

The X-axis in Figure 1 represents the channel values, going from 0 to 255.  The Y-axis represents the observed rotational velocity based on measuring the time it takes for the head to move some number of degrees with a stop watch.  You can construct a graph like Figure 1 using a lighting desk and your fixture with the following procedure: 1) set the fixture’s DMX channel for speed to a value between 0 and 255, 2) move the head angle to 180 degrees, 3) start the stop watch and simultaneously quickly change the DMX channel value for head angle to aim it back at zero degrees, 4) record the time it took to travel 180 degrees, 5) the degrees per second is thus 180 / measured time.

Based on your measurements you can connect the dots to make a curve, and then you can define a mathematical curve that approximates the measured curve with the parameters of the :defineFunc1 or :defineFunc2 functions, as shown in Table 3.  When referenced by parameter :speedFromEffectiveSetupAndFunc1 the result of the function :defineFunc1 is interpreted to be “speed” in degrees per second.  When referenced by :timeFromEffectiveSetupAndFunc1 the result is interpreted to be “time” in seconds.

Table 3 – Parameters of the functions defined by :defineFunc1 and :defineFunc2

The parameters define the function as an interpolation between the speed at 0 and the speed at 255 (parameters +1 and +2) by way of the function chosen by parameter +0 with exponent C from parameter +3, the result clamped by optional parameters +4 and +5.  If C is 1, then the function is simply a straight line.  If C is 2 then the curve is a parabola.  Other values of C, including fractional values, produce different curves with different bends.  You can choose :power or :rpower and find a value for C that yields a decent approximation to your measured values by graphing the functions in Excel and adjusting the values to find the best fit.

The third example from the beginning of this article included the defined function for the 80W Tomshine fixture of Figure 1:

:defineFunc1 :power 250 1 1.6

From Table 3, you can see this function begins with 250 degrees/sec at DMX speed channel value = 0, ends with 1 degree/sec at DMX speed channel value 255, and uses the power C = 1.6.  That produces the yellow line in Figure 1.  The knee of the curve is closest to DMX speed channel value = 0.  If you want the knee to be on the other end, at 255, then try the function :rpower instead.  If the observed motor speed essentially stops before reaching the maximum DMX channel value, you may find it useful to specify a negative value for parameter +1 or +2 to make the curve cross the X-axis at the right DMX channel value.

End value optimizations

The end value for DMX channels specified in the setupBeginEndPatch and beginEndPatch (but not beginForeverPatch and endForeverPatch) code segments may be changed to zero in some circumstances to facilitate optimizations that reduce the size of the script file for certain firing systems.  If the specified end value is X, that means, “X, or optionally zero if the next event that sets this channel sets it to zero.”  These semantics enable the DMX script exporter to use a feature of some firing systems that automatically sets the value of a channel to zero after a given duration without requiring an additional script row to set it to zero.

In some cases, DMX Patches need to work around the end value optimizations to avoid visual ramifications.  The MARQ moving head fixture’s shutter channel value range of 0-3 corresponds to closed, beam not visible.  The DMX Patch for the initialize fixture effect sets the shutter to remain with an “end” value of 255 (“open, beam visible”), but “end” values in DMX Patches may be changed by the exporter to 0 as a valid optimization if the following event begins with the value 0 for the same channel.  Consequently, if an event begins with shutter channel value of 0 it could affect a previous shutter value (for instance, changing the “end” value of the initialize fixture from 255 to 0).  To prevent this unfortunate side-effect of the shutter channel value of 0, the MARQ DMX Patches simply never use the shutter value of 0; the values 1-3 are equivalent and do not cause end value optimizations.

Move-In-Black and Move-To

For moving head fixtures, the DMX Patches for Move-In-Black effects set the dimmer value (or RGB values directly if dimmer is combined with strobe on the same channel) to zero (OFF) instead of leaving it unchanged, for reasons that are a little complicated.  Move-To effects begin their nominal interpolation period at the effect time of the previous non-modifier event on the fixture (modifier events like “With Strobing” or “With Gobo” contain the word “Modifier” in their VDL to avoid affecting the Move-To interpolation periods).  While the nominal interpolation period extends back to the effect time of the previous non-modifier event, each affected DMX channel’s interpolation period extends back to previous time the DMX channel itself was set.  If the Move-In-Black effects don’t set the dimmer value to zero, then a Move-To effect that follows the Move-In-Black effect will cause the dimmer to be ON beginning prior to the Move-In-Black effect!

For precisely the reasons that Move-In-Black effects do set the dimmer value, they do not set the color wheel parameter or gobo parameter for fixtures with rotating wheel mechanisms, because a Move-To effect that follows the Move-In-Black effect does need to cause the wheel parameters to be set prior to the Move-In-Black effect time, so the wheels have time to rotate properly before the effect turns on visibly at exactly the Move-In-Black effect time.

You can string multiple Move-To events together, e.g., Move-In-Black, Move-To, Move-To, Move-To, etc.  It is clearer to begin a Move-To sequence with a Move-In-Black, but users may begin them with a Flash effect instead.  It is imperative that the DMX Patch of a Flash effect sets the motor speed to full speed, just as the Move-In-Black does.  Otherwise a Move-To effect following the Flash effect will likely cause the motor speed to be set to a slower speed prior to the Flash effect, sabotaging its ability to achieve the desired pan/tilt angle by the time of the Flash effect.

Table 4 and Table 5 provide patch templates for fixtures with color wheels (Example: YF [081] Beam 230 Moving Head 16CH), and fixtures with RGB LEDs an independent dimmer channel (Example: U `King [029] Moving Head RGBW 11CH).  Some fixtures with LEDs combine the dimmer and strobe on the same DMX channel (Example: Betopper [090] DJ Mini Moving Head 9CH).   Patches for such fixtures use the RGB channels rather than the strobe+dimmer channel to turn the lights on so the strobe+dimmer channel can be used to control strobing independently, essentially ignoring its application as a dimmer.  These patches are described in Table 6.

Multi-function fixtures that combine LEDs and lasers using a single dimmer channel globally for both the LEDs and the lasers may need to use patches similar to those in Table 6, essentially ignoring the dimmer channel so the LEDs and lasers can be turned on independently (Example: U `King [089] Pocket Moving Kaleidoscope/Laser 15CH).

Table 4 – Flash, Move-To and Move-In-Black patch templates for fixtures with color wheels

Table 5 – Flash, Move-To and Move-In-Black patch templates for fixtures with RGB LEDs; and with dimmer that is not combined with strobe on the same channel 

Table 6 – Flash, Move-To and Move-In-Black patch templates for fixtures with RGB LEDs; and with dimmer that is combined with strobe on the same channel 

With XXX

By convention, effects that modify other effects and do not have a visual effect on their own are named “With XXX” where XXX is a description of an effect modification that applies for the duration of the effect.   These are called “modifier effects”.  Examples are “With Strobing” or “With Safety Channel”.  As described in Table 2 of  Creating or modifying DMX effects for existing fixtures, the VDL of modifier effects should contain the term “Modifier” and “Non-Physical” to make them appear correctly on the timeline and to prevent them from interfering with the effective setup time for Move-To interpolation.

Reset Fixture

Table 7 – Example files