Software Documentation

Software Documentation

DMXDocumentation

Hobbyist Pro Last updated: May 26, 2024

14 Programmer documentation: The DMX Patch field

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

Function name Meaning Parameters
beginEndPatch Defines the DMX channel values to occur at the beginning of the effect and at the end of the effect. A list of 3 * N parameters, for N channel specifications; the first three parameters specifying the channel offset, begin-value, and end-value of the first channel specification, the next three parameters specifying the channel offset, begin-value, and end-value of the second channel specification, etc.  Additional optional parameters may follow if entailed by earlier parameters such as :defineFunc1.
setupBeginEndPatch Defines the DMX channel values to occur at the beginning of the setup time, and at the beginning of the effect, and at the end of the effect. A list of 1 + 4 * N parameters, for N channel specifications; the first parameter specifying the ideal setup time in milliseconds, evaluated independently for each DMX channel in the DMX patch; the next four parameters specifying the channel offset, setup-value, begin-value, and end-value of the first channel specification, the next four parameters specifying the channel offset, setup-value, begin-value, and end-value of the second channel specification, etc.  Additional optional parameters may follow if entailed by earlier parameters such as :defineFunc1.
beginForeverPatch Defines the DMX channel values to occur at the beginning of the effect and to persist forever or until the interrupted by a subsequent effect. A list of 2 * N parameters, for N channel specifications; the first two parameters specifying the channel offset and begin-value of the first channel specification, the next two parameters specifying the channel offset and begin-value of the second channel specification, etc.; no channel changes occur at the end of the event.  Additional optional parameters may follow if entailed by earlier parameters such as :defineFunc1.
endForeverPatch Defines the DMX channel values to occur at the end of the effect and to persist forever or until the interrupted by a subsequent effect. A list of 2 * N parameters, for N channel specifications; the first two parameters specifying the channel offset and end-value of the first channel specification, the next two parameters specifying the channel offset and end-value of the second channel specification, etc.; no channel changes occur at the beginning of the event.  Additional optional parameters may follow if entailed by earlier parameters such as :defineFunc1.

 

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

Parameter name Evaluates to Meaning
:duration10 0-255 channel value Effect duration in hundredths of a second
:duration500MsTo2500Ms 0-255 channel value Effect duration from 500ms to 2500ms, mapped to 0 to 255, clamped at the edges
:customPartFieldExploX2 0-255 channel value The value ( 2 + X * 255.0 / 100.0 ) rounded to the nearest integer, where X is the Custom Part Field value of the effect, read as an integer; this calculation converts the Explo X2 pre-defined macro numbers to the DMX channel value range 0-255
:speedFromEffectiveSetupAndFunc1 (or :spdFrmESetupF1) 0-255 channel value A speed value in the range 0-255 calculated from (1) the “effective setup time” (as defined earlier) and (2) the angle delta in pan or tilt (whichever delta is greater) between this event and the nearest preceding event whose VDL does not contain the keyword “Modifier”, and (3) the function defined by the optional parameter :defineFunc1 (see Table 3)
:speedFromEffectiveSetupAndFunc2 (or :spdFrmESetupF2) 0-255 channel value Like :speedFromEffectiveSetupAndFunc1 but using the function defined by :defineFunc2
:defineFunc1 N/A Defines a function to calculate the speed parameter for a fixture based on the effect duration and angle interval; useful for moving head fixtures (see Table 3).

“Move-To” effects need to calculate a “motor speed” parameter based on the angle sweep delta and the duration of the sweep. It would be nice if the speed calculation was simple, such as: speed = angle delta / duration. Unfortunately the motor speeds on different fixtures are not linear, and their min/max speeds are different from fixture to fixture. So Finale 3D‘s DMX Patch in the effect needs to define a function to calculate the speed based on the angle delta and duration. That is what :defineFunc1 does.

:defineFunc2 N/A Like :defineFunc1
:effectiveSetupPlus1000Ms Integer for first parameter of setupBeginEndPatch Integer milliseconds suitable for the first parameter of of the setupBeginEndPatch function; “Move-To” effects make channel changes to visible attributes at a time that reaches back by the effective setup time to connect with the preceding effect (such as a “Move-In-Black (MIB)” effect), but if a “Move-To” effect has a gobo, the gobo channels need to be set even in advance of the effective setup time in order to be fully rotated at the time the visible attributes change; the extra 1000ms provides a time point for the DMX Patch to set the gobo channels or color wheel channels.

As an example, imagine you begin at time t=10sec with the head aiming straight up, turned OFF.  Then from time t = 20s to time t = 22s you want to do an angle sweep from -45 degrees to 45 degrees with the head turned on RED.  The event at time t = 20s would be the “Move-In-Black” effect.  The event at time t = 22s would be the  “Move-To” effect.  The “Move-To” effect needs to turn the light ON at t = 20s with the color RED, but if the fixture uses a color wheel, the color wheel takes some time to rotate to the correct color, so the color wheel channel parameter needs to be set in advance of t = 20s so that when the light is turned on at 20sec the color wheel is already at the correct rotation to show the color RED.   Thus the  “Move-To” effect at time t = 22s needs to reach back 2s + some extra time to set the color wheel rotation.

:effectiveSetup10 0-255 channel value The effective setup time in hundredths of a second
:effectiveSetup Integer for first parameter of setupBeginEndPatch The effective setup time in milliseconds
:nominalSetup Integer for first parameter of setupBeginEndPatch The prefire time of the effect definition in milliseconds (from the Prefire column in the effects window)
:pan540 0-255 channel value The pan angle of the effect (right hand rotation around Up-axis), mapped from 0-540 degrees to the value 0-255; the calculation is, (“Effect’s Pan in Finale 3D converted to 0-360 degrees” * 127.5 / 270 ) rounded to the nearest integer.
:rPan540 0-255 channel value Like :pan540 except calculated from the negated Pan angle in Finale 3D, converted to 0-360 degrees.
:rTilt230 0-255 channel value Like :tilt230 except calculated from the negated Tilt angle in Finale 3D, converted to -180 to 180 degrees.
:rTilt244 0-255 channel value Like :tilt244 except calculated from the negated Tilt angle in Finale 3D, converted to -180 to 180 degrees.
:rTilt270 0-255 channel value Like :tilt270 except calculated from the negated Tilt angle in Finale 3D, converted to -180 to 180 degrees.
:rTilt180 0-255 channel value Like :tilt180 except calculated from the negated Tilt angle in Finale 3D, converted to -180 to 180 degrees.
:rTilt180z5 5-250 channel value Like :rTilt180 except clamped to the range 5 to 250, supporting fixtures for which 0 or 255 values have special meaning.
:tilt210 0-255 channel value The tilt angle of the effect, i.e., bending forward/back or left/right (right hand rotation around Pan-rotated Right-axis), mapped from -105 to 105 degrees to the value 0-255; the calculation is, (“Effect’s Tilt in Finale 3D converted to -180 to 180 degrees” * 127.5 / 105 + 127.5 ) rounded to the nearest integer.
:rTilt210 0-255 channel value Like :tilt210 except calculated from the negated Tilt angle in Finale 3D, converted to -180 to 180 degrees.
:tiltL76R255 76-255 channel value The tilt angle of the effect, mapped from -90 to 90 degrees to the value 76-255; the calculation is, (“Effect’s Tilt in Finale 3D converted to -180 to 180 degrees” * 89.5 / 90 + 165.5 ) rounded to the nearest integer and clamped to the valid range.
:rTiltL76R255 76-255 channel value Like :tiltL76R255except calculated from the negated Tilt angle in Finale 3D, converted to -180 to 180 degrees.
:tilt90x200 0-255 channel value The tilt angle of the effect, i.e., bending forward/back or left/right (right hand rotation around Pan-rotated Right-axis), mapped from -45 to 45 degrees to the value 28 to 228; the calculation is, (“Effect’s Tilt in Finale 3D converted to -180 to 180 degrees” * 100.0 / 45 + 127.5 ) rounded to the nearest integer and clamped to 28 – 228
:tilt45ToChannelOffset0To4 0-4 channel offset A channel offset 0-4 representing best nearest match fixed angle fixture head, for fixture heads at -45, -22.5, 0, 22.5, 45 matching the tilt angle of the effect
:tilt45ToChannelOffset1To5 1-5 channel offset Like :tilt45ToChannelOffset0To4 except offsets beginning at 1 instead of 0
:tilt45ToChannelOffset1To3 1-3 channel offset Like :tilt45ToChannelOffset1To5 except for three fixture heads at -45, 0, and 45 degrees
:rTilt45ToChannelOffset0To4 0-4 channel offset Like :tilt45ToChannelOffset0To4 except except calculated from the negated Tilt angle in Finale 3D
:rTilt45ToChannelOffset1To5 1-5 channel offset Like :tilt45ToChannelOffset1To5 except except calculated from the negated Tilt angle in Finale 3D
:rTilt45ToChannelOffset1To3 1-3 channel offset Like :tilt45ToChannelOffset1To3 except except calculated from the negated Tilt angle in Finale 3D
:tilt40ToChannelOffset0To4 0-4 channel offset A channel offset 0-4 representing best nearest match fixed angle fixture head, for fixture heads at -40, -20, 0, 20, 40 matching the tilt angle of the effect
:tilt40ToChannelOffset1To5 1-5 channel offset Like :tilt40ToChannelOffset0To4 except offsets beginning at 1 instead of 0
:tilt40ToChannelOffset1To3 1-3 channel offset Like :tilt40ToChannelOffset1To5 except for three fixture heads at -40, 0, and 40 degrees
:rTilt40ToChannelOffset0To4 0-4 channel offset Like :tilt40ToChannelOffset0To4 except except calculated from the negated Tilt angle in Finale 3D
:rTilt40ToChannelOffset1To5 1-5 channel offset Like :tilt40ToChannelOffset1To5 except except calculated from the negated Tilt angle in Finale 3D
:rTilt40ToChannelOffset1To3 1-3 channel offset Like :tilt40ToChannelOffset1To3 except except calculated from the negated Tilt angle in Finale 3D
:tilt180 0-255 channel value The tilt angle of the effect, i.e., bending forward/back or left/right (right hand rotation around Pan-rotated Right-axis), mapped from -90 to 90 degrees to the value 0-255; the calculation is, (“Effect’s Tilt in Finale 3D converted to -180 to 180 degrees” * 127.5 / 90 + 127.5 ) rounded to the nearest integer.
:tilt180z5 0-255 channel value Like :tilt180 except clamped to the range 5 to 250, supporting fixtures for which 0 or 255 values have special meaning.
:tilt230 0-255 channel value The tilt angle of the effect, i.e., bending forward/back or left/right (right hand rotation around Pan-rotated Right-axis), mapped from -115 to 115 degrees to the value 0-255; the calculation is, (“Effect’s Tilt in Finale 3D converted to -180 to 180 degrees” * 127.5 / 115 + 127.5 ) rounded to the nearest integer.
:tilt244 0-255 channel value The tilt angle of the effect, i.e., bending forward/back or left/right (right hand rotation around Pan-rotated Right-axis), mapped from -122 to 122 degrees to the value 0-255; the calculation is, (“Effect’s Tilt in Finale 3D converted to -180 to 180 degrees” * 127.5 / 122 + 127.5 ) rounded to the nearest integer.
:tilt270 0-255 channel value The tilt angle of the effect, i.e., bending forward/back or left/right (right hand rotation around Pan-rotated Right-axis), mapped from -135 to 135 degrees to the value 0-255; the calculation is, (“Effect’s Tilt in Finale 3D converted to -180 to 180 degrees” * 127.5 / 135 + 127.5 ) rounded to the nearest integer.
:timeFromEffectiveSetupAndFunc1 (or :tmFrmESetupF1) 0-255 channel value A time value in the range 0-255 calculated from the “effective setup time” (as defined earlier) and (2) the angle delta in pan or tilt (whichever delta is greater) between this event and the nearest preceding event whose VDL does not contain the keyword “Modifier”, and (3) the function defined by the optional parameter :defineFunc1 (see Table 3)
:timeFromEffectiveSetupAndFunc2 (or :tmFrmESetupF2) 0-255 channel value Like :timeFromEffectiveSetupAndFunc1 but using the function defined by :defineFunc2

 

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

Parameter index Meaning Values
+0 Name of interpolation function:
:power means Y=(Y1-Y0)* ((X-X0)/(X1-X0))^C+Y0
:rpower means Y=(Y0-Y1)*((X1-X)/X1-X0))^C+Y1
where X0=the DMX channel value 0, X1=the DMX channel value 255, Y0=Degrees/sec at DMX channel value 0, Y1= the function value (e.g., degrees/sec or seconds) at DMX channel value 255, C=exponent defined in parameter +3 that affects the shape of the curve
:power or :rpower
+1 The function value for the DMX channel value 0 (Y0 in the interpolation function) float
+2 The function value for the DMX channel value 255 (Y1 in the interpolation function) float
+3 The constant exponent C of the interpolation function (C = 1.0 means linear interpolation) float
+4 (optional) Min valid DMX value on the X-axis if not zero (to restrict value range to reliable values for the fixture; e.g., Explo X2 Wave Flamer does not work reliably for values < 25 or > 128) integer 0-255
+5 (optional) Max valid DMX value on the X-axis if not 255 integer 0-255

 

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

Type Of Effect Patch
Red Flash [setupBeginEndPatch 1000 PANINDEX :pan540 :pan540 :pan540 TILTINDEX :rTilt230 :rTilt230 :rTilt230 COLORINDEX COLORVALUE COLORVALUE COLORVALUE DIMMERINDEX 0 255 0 SPEEDINDEX 0 0 0]
Move-In-Black [setupBeginEndPatch 1000 PANINDEX :pan540 :pan540 :pan540 TILTINDEX :rTilt230 :rTilt230 :rTilt230 DIMMERINDEX 0 0 0 SPEEDINDEX 0 0 0]
Red Move-To [setupBeginEndPatch :effectiveSetupPlus1000Ms PANINDEX :pan540 :pan540 :pan540 TILTINDEX :rTilt230 :rTilt230 :rTilt230 COLORINDEX COLORVALUE COLORVALUE COLORVALUE
DIMMERINDEX 255 255 0 SPEEDINDEX :spdFrmESetupF1 :spdFrmESetupF1 :spdFrmESetupF1]

 

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 

Type Of Effect Patch
Red Flash [setupBeginEndPatch 1000 PANINDEX :pan540 :pan540 :pan540 TILTINDEX :rTilt230 :rTilt230 :rTilt230 RINDEX RVALUE RVALUE RVALUE GINDEX GVALUE GVALUE GVALUE BINDEX BVALUE BVALUE BVALUE DIMMERINDEX 0 255 0 SPEEDINDEX 0 0 0]
Move-In-Black [setupBeginEndPatch 1000 PANINDEX :pan540 :pan540 :pan540 TILTINDEX :rTilt230 :rTilt230 :rTilt230 DIMMERINDEX 0 0 0 SPEEDINDEX 0 0 0]
Red Move-To [setupBeginEndPatch :effectiveSetupPlus1000Ms PANINDEX :pan540 :pan540 :pan540 TILTINDEX :rTilt230 :rTilt230 :rTilt230 RINDEX RVALUE RVALUE RVALUE GINDEX GVALUE GVALUE GVALUE BINDEX BVALUE BVALUE BVALUE DIMMERINDEX 255 255 0 SPEEDINDEX :spdFrmESetupF1 :spdFrmESetupF1 :spdFrmESetupF1]

 

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 

Type Of Effect Patch
Red Flash [setupBeginEndPatch 1000 PANINDEX :pan540 :pan540 :pan540 TILTINDEX :rTilt230 :rTilt230 :rTilt230 RINDEX 0 RVALUE 0  GINDEX 0 GVALUE 0 BINDEX 0 BVALUE 0 SPEEDINDEX 0 0 0]
Move-In-Black [setupBeginEndPatch 1000 PANINDEX :pan540 :pan540 :pan540 TILTINDEX :rTilt230 :rTilt230 :rTilt230 RINDEX 0 0 0  GINDEX 0 0 0 BINDEX 0 0 0 SPEEDINDEX 0 0 0]
Red Move-To [setupBeginEndPatch :effectiveSetupPlus1000Ms PANINDEX :pan540 :pan540 :pan540 TILTINDEX :rTilt230 :rTilt230 :rTilt230 RINDEX RVALUE RVALUE 0  GINDEX GVALUE GVALUE 0 BINDEX BVALUE BVALUE 0 SPEEDINDEX :spdFrmESetupF1 :spdFrmESetupF1 :spdFrmESetupF1]

 

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

Some fixtures require a “Reset/Initialize Fixture” effect to set certain DMX channels to initial values.  It is most common for DMX channel values of 0 to correspond to natural default values, but that’s just not the case for some fixtures.  The 30W Tomshine moving head fixture’s “no gobo” pattern does not correspond to the DMX gobo channel value of 0; it corresponds to values between 16 and 23!    The flash effects for this fixture do not themselves set the gobo channel, in order to allow “With Gobo” effects to apply the gobo as a modification.  Thus if the gobo channel value of 0 corresponds to a gobo, the user is in for a surprise unless the user adds a “Reset Fixture” effect that sets the gobo channel value to a number between 16 and 23 to nullify the gobo pattern.
The fixtures requiring a “Reset/Initialize Fixture” effect are listed in Table 1 of Supported light fixtures (and Standard Fixture IDs).

 

Table 7 – Example files

Download link Explanation
dmx_patch_functions02.xlsx Excel worksheet for defining functions